@prosopo/user-access-policy 3.11.3 → 3.12.1

package/src/redis/reader/redisRulesReader.ts

@@ -20,6 +20,7 @@ import {
 	REDIS_QUERY_DIALECT,
 	getRulesRedisQuery,
 } from "#policy/redis/reader/redisRulesQuery.js";
+import { buildScopedBlockSubQueries } from "#policy/redis/reader/redisRulesSplitQuery.js";
 import {
 	REDIS_BATCH_SIZE,
 	fetchRedisHashRecords,
@@ -63,6 +64,16 @@ export const SERVER_SIDE_RANK_TOP_N = 20;
 // per-request path.
 const GREEDY_MAX_CANDIDATES = REDIS_BATCH_SIZE * 10;
 
+// Per-sub-query cap on the hot split-query path. Each sub-query probes a
+// single discriminating index (a specific numericIp value, a specific
+// ja4Hash value, etc.) so the natural cardinality is tiny — typically
+// 1–5. The cap only fires on pathological rule-set shapes (e.g. many
+// duplicate-value rules against one attribute) and prevents a bad shape
+// from tanking the request. It intentionally lets the union grow past
+// SERVER_SIDE_RANK_TOP_N because JS-side rankCandidateRules picks the
+// winner and the extra candidates are cheap to HGETALL.
+const SPLIT_MAX_CANDIDATES_PER_SUB = 500;
+
 // Fields that contribute one specificity point each. Mirrors
 // SCALAR_USER_SCOPE_FIELDS + clientId + ip-constraint in
 // blacklistRequestInspector.ruleSpecificity. numericIp and the
@@ -166,16 +177,38 @@ export class RedisRulesReader implements AccessRulesReader {
 	): Promise<AccessRule[]> {
 		const query = getRulesRedisQuery(filter, matchingFieldsOnly);
 
-		if (skipEmptyUserScopes && query === "ismissing(@clientId)") {
-			// We don't want to accidentally return all rules when the filter is empty
+		if (
+			skipEmptyUserScopes &&
+			// Sentinel query shape emitted by getPolicyScopeQuery when the
+			// caller passed neither a userScope nor a clientId — i.e. an
+			// empty filter that would otherwise resolve to "all global
+			// rules". Guard so an accidentally-empty filter can't return
+			// the full global rule set. The exact literal must stay in
+			// sync with GLOBAL_MATCH_CLAUSE_INNER over there.
+			query === "( @clientId:{global} | ismissing(@clientId) )"
+		) {
 			return [];
 		}
 
-		// Hot path: strict-match callers (blockMiddleware /
-		// checkForHardBlock) get server-side specificity ranking via
-		// FT.AGGREGATE — Redis returns the top N candidates already
-		// sorted, no HGETALL fanout. See SPECIFICITY_EXPR / RANK_EXPR
-		// above for the score definition.
+		// Hot path (checkForHardBlock / blockMiddleware): the strict-match
+		// caller passes blockOnly + a userScope, and every field returned
+		// gets JS-side re-ranked by rankCandidateRules anyway. Route it
+		// through the split-query path — one FT probe per populated
+		// request field, each using its own posting list — instead of the
+		// single wide FT.AGGREGATE whose APPLY step scaled linearly in
+		// the tenant's total rule count and tipped over under large
+		// bulk-ban populations.
+		if (
+			matchingFieldsOnly &&
+			filter.blockOnly &&
+			filter.userScope !== undefined
+		) {
+			return this.findBlockRulesSplit(filter);
+		}
+
+		// Non-hot-path matchingFieldsOnly (e.g. Restrict-only lookups):
+		// keep the pre-existing server-side-ranked single query. Not on
+		// the hot path so the APPLY overhead is acceptable.
 		if (matchingFieldsOnly) {
 			return this.findRulesRanked(filter, query);
 		}
@@ -186,6 +219,111 @@ export class RedisRulesReader implements AccessRulesReader {
 		return this.findRulesGreedy(filter, query);
 	}
 
+	// Union candidate keys from each split sub-query, de-dupe, HGETALL,
+	// parse, hand back to `getPrioritisedAccessRule` for JS-side ranking.
+	// Ranking stays in JS because rankCandidateRules already encodes the
+	// strict "every populated rule field matches request" semantics —
+	// FT can't express that shape cheaply and the previous server-side
+	// APPLY / SORTBY imposed the linear-per-rule cost we're eliminating.
+	private async findBlockRulesSplit(
+		filter: AccessRulesFilter,
+	): Promise<AccessRule[]> {
+		const userScope = filter.userScope;
+		if (userScope === undefined) {
+			return [];
+		}
+		const clientId = filter.policyScope?.clientId;
+
+		const subQueries = buildScopedBlockSubQueries(userScope, clientId);
+
+		try {
+			const keyLists = await Promise.all(
+				subQueries.map((sub) =>
+					aggregateRedisKeys(
+						this.client,
+						sub.query,
+						this.logger,
+						undefined,
+						// Per-sub-query cap. Each probe hits a discriminating
+						// index (e.g. numericIp posting list), so the natural
+						// cardinality is tiny — this cap only fires on
+						// pathological rule-set shapes and mirrors
+						// SPLIT_MAX_CANDIDATES_PER_SUB below.
+						SPLIT_MAX_CANDIDATES_PER_SUB,
+					).catch((err) => {
+						// One sub-query failing (e.g. a transient RediSearch
+						// error) shouldn't drop the whole lookup — the other
+						// probes may still find the applicable rule. Log and
+						// continue with an empty result for this probe.
+						this.logger.error(() => ({
+							err,
+							data: {
+								inspect: util.inspect(
+									{ subKind: sub.kind, query: sub.query },
+									{ depth: null },
+								),
+							},
+							msg: "failed to execute split block sub-query",
+						}));
+						return [];
+					}),
+				),
+			);
+
+			const uniqueKeys = new Set<string>();
+			for (const list of keyLists) {
+				for (const key of list) {
+					uniqueKeys.add(key);
+				}
+			}
+
+			if (uniqueKeys.size === 0) {
+				return [];
+			}
+
+			const ruleKeys = [...uniqueKeys];
+
+			this.logger.debug(() => ({
+				msg: "Executed split block sub-queries",
+				data: {
+					inspect: util.inspect(
+						{
+							subQueryCount: subQueries.length,
+							uniqueCandidates: ruleKeys.length,
+							perSubQueryCounts: keyLists.map((l, i) => ({
+								kind: subQueries[i]?.kind,
+								found: l.length,
+							})),
+							filter,
+						},
+						{ depth: null },
+					),
+				},
+			}));
+
+			const { records } = await fetchRedisHashRecords(
+				this.client,
+				ruleKeys,
+				this.logger,
+			);
+
+			const nonEmptyRecords = records.filter(
+				(record) => Object.keys(record).length > 0,
+			);
+
+			return parseRedisRecords(nonEmptyRecords, accessRuleInput, this.logger);
+		} catch (e) {
+			this.logger.error(() => ({
+				err: e,
+				data: {
+					inspect: util.inspect({ filter }, { depth: null }),
+				},
+				msg: "failed to execute split block query set",
+			}));
+			return [];
+		}
+	}
+
 	private async findRulesRanked(
 		filter: AccessRulesFilter,
 		query: string,

package/src/redis/reader/redisRulesSplitQuery.ts

@@ -0,0 +1,170 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {
+	AccessPolicyType,
+	GLOBAL_CLIENT_SCOPE_SENTINEL,
+	type UserScope,
+} from "#policy/rule.js";
+
+// Escapes special characters in Redis TAG queries. Mirrors the escape
+// function in redisRulesQuery.ts — kept local to avoid coupling the two
+// query builders since they'll diverge in shape.
+const escapeTagValue = (value: string): string =>
+	value.replace(/([,.<>{}\[\]"':;!@#$%^&*()\-+=~|/\\])/g, "\\$1");
+
+// Fields where TAG queries need escaping (they may hold JSON etc.).
+const FIELDS_REQUIRING_ESCAPE: ReadonlySet<keyof UserScope> = new Set([
+	"coords",
+]);
+
+// Fields indexed as NUMERIC — require range syntax `@x:[N N]` not TAG.
+const NUMERIC_FIELDS: ReadonlySet<keyof UserScope> = new Set(["asn"]);
+
+// Enumerating the scalar (non-IP) user-scope fields keeps the "no
+// user-scope constraint" fall-through query stable when userScopeSchema
+// grows a new field — the enumeration below drives ismissing() clauses.
+const SCALAR_USER_SCOPE_FIELDS: ReadonlyArray<keyof UserScope> = [
+	"userId",
+	"ja4Hash",
+	"headersHash",
+	"userAgentHash",
+	"headHash",
+	"coords",
+	"countryCode",
+	"asn",
+];
+
+const ALL_USER_SCOPE_FIELDS: ReadonlyArray<keyof UserScope> = [
+	...SCALAR_USER_SCOPE_FIELDS,
+	"numericIp",
+	"numericIpMaskMin",
+	"numericIpMaskMax",
+];
+
+// Global rules written under the new sentinel are found via
+// `@clientId:{global}`; the ismissing() fallback covers legacy rules
+// that predate the sentinel stamp (rehash-all migrates them). This
+// disjunction still hits the clientId posting list rather than walking
+// the full rule set the way the old single-query path did.
+const GLOBAL_SCOPE_INNER = `@clientId:{${GLOBAL_CLIENT_SCOPE_SENTINEL}} | ismissing(@clientId)`;
+
+const buildScopeClause = (clientId: string | undefined): string => {
+	if (clientId === undefined) {
+		return `( ${GLOBAL_SCOPE_INNER} )`;
+	}
+	return `( @clientId:{${clientId}} | ${GLOBAL_SCOPE_INNER} )`;
+};
+
+const buildFieldClause = (
+	field: keyof UserScope,
+	value: unknown,
+): string | null => {
+	if (value === undefined) {
+		return null;
+	}
+	const stringValue = String(value);
+	if (NUMERIC_FIELDS.has(field)) {
+		return `@${field}:[${stringValue} ${stringValue}]`;
+	}
+	const queryValue = FIELDS_REQUIRING_ESCAPE.has(field)
+		? escapeTagValue(stringValue)
+		: stringValue;
+	return `@${field}:{${queryValue}}`;
+};
+
+type SubQuery = {
+	// A short label used for logging + metrics. Not part of the query
+	// wire format.
+	kind: string;
+	query: string;
+};
+
+/**
+ * Build the set of FT sub-queries that together cover every rule that
+ * could apply to a request for hard-block resolution.
+ *
+ * The single-query design this replaces produced one FT.AGGREGATE whose
+ * candidate set was the entire scope's rule pool — the APPLY / SORTBY
+ * pipeline then walked every rule per request, which degrades sharply
+ * once rule populations reach the 10k+ range. The split approach fires
+ * one probe per populated request field. Each probe uses the field's
+ * own index posting list, so a 17k IP-ban population collapses to 1
+ * result (exact IP) plus a handful (CIDR ranges containing the IP)
+ * instead of forcing a full-set scan.
+ *
+ * A single fall-through probe covers rules with no user-scope constraint
+ * (client-wide block); those are rare so the ismissing()-heavy query is
+ * cheap in practice.
+ *
+ * Rank + strict-match filtering happens in JS via `rankCandidateRules`
+ * after the union — the FT layer is used purely as a candidate fetcher.
+ */
+export const buildScopedBlockSubQueries = (
+	userScope: UserScope,
+	clientId: string | undefined,
+): SubQuery[] => {
+	const typeClause = `@type:{${AccessPolicyType.Block}}`;
+	const scopeClause = buildScopeClause(clientId);
+	const prefix = `${typeClause} ${scopeClause}`;
+
+	const subQueries: SubQuery[] = [];
+
+	// One probe per populated scalar user-scope field. Each uses that
+	// field's posting list rather than intersecting ismissing() across
+	// the full set.
+	for (const field of SCALAR_USER_SCOPE_FIELDS) {
+		const clause = buildFieldClause(field, userScope[field]);
+		if (clause === null) {
+			continue;
+		}
+		subQueries.push({
+			kind: `field:${field}`,
+			query: `${prefix} ${clause}`,
+		});
+	}
+
+	// IP: two disjoint probes so each hits a single index. The exact-IP
+	// probe catches individual-IP bans (the dominant shape in bulk-ban
+	// scripts). The mask-range probe catches CIDR aggregates containing
+	// the request IP. Splitting them means neither has to walk a mixed
+	// posting list — the mask-range probe was the slower of the two
+	// under load, so isolating it lets Redis skip it entirely for hits
+	// on the fast path.
+	const requestIp = userScope.numericIp;
+	if (requestIp !== undefined) {
+		subQueries.push({
+			kind: "ip:exact",
+			query: `${prefix} @numericIp:[${requestIp} ${requestIp}]`,
+		});
+		subQueries.push({
+			kind: "ip:mask",
+			query: `${prefix} @numericIpMaskMin:[-inf ${requestIp}] @numericIpMaskMax:[${requestIp} +inf]`,
+		});
+	}
+
+	// Fall-through: rules that constrain nothing on the user scope
+	// ("block everything for this client / everyone"). Rare in
+	// practice — a handful per tenant at most — so the ismissing()
+	// intersection is cheap despite touching every field.
+	const noScopeIsmissing = ALL_USER_SCOPE_FIELDS.map(
+		(field) => `ismissing(@${field})`,
+	).join(" ");
+	subQueries.push({
+		kind: "no-user-scope",
+		query: `${prefix} ${noScopeIsmissing}`,
+	});
+
+	return subQueries;
+};

package/src/redis/redisRuleIndex.ts

@@ -80,6 +80,12 @@ export const ACCESS_RULES_REDIS_INDEX_NAME = "index:user-access-rules";
 // names take space, so we use an acronym instead of the long-tailed one
 export const ACCESS_RULE_REDIS_KEY_PREFIX = "uar:";
 
+// Re-exported from #policy/rule.js — that module is types-only so both
+// the parse side (policyInput.ts) and the write/index side (this file
+// and redisRulesWriter.ts) can import the sentinel without pulling
+// transformRule into a cycle.
+export { GLOBAL_CLIENT_SCOPE_SENTINEL } from "#policy/rule.js";
+
 export const accessRulesRedisIndex: RedisIndex = {
 	name: ACCESS_RULES_REDIS_INDEX_NAME,
 	schema: accessRuleRedisSchema,

package/src/redis/redisRulesWriter.ts

@@ -16,7 +16,7 @@ import { chunkIntoBatches, executeBatchesSequentially } from "@prosopo/common";
 import type { Logger } from "@prosopo/logger";
 import type { RedisClientType } from "redis";
 import { REDIS_BATCH_SIZE } from "#policy/redis/redisClient.js";
-import type { AccessRule } from "#policy/rule.js";
+import { type AccessRule, GLOBAL_CLIENT_SCOPE_SENTINEL } from "#policy/rule.js";
 import type {
 	AccessRuleEntry,
 	AccessRulesWriter,
@@ -120,10 +120,24 @@ export class RedisRulesWriter implements AccessRulesWriter {
 	}
 }
 
-export const getRedisRuleValue = (rule: AccessRule): Record<string, string> =>
-	Object.fromEntries(
-		Object.entries(rule).map(([key, value]) => [key, String(value)]),
-	);
+export const getRedisRuleValue = (rule: AccessRule): Record<string, string> => {
+	const record: Record<string, string> = {};
+	for (const [key, value] of Object.entries(rule)) {
+		if (value === undefined) {
+			continue;
+		}
+		record[key] = String(value);
+	}
+	// Global rules used to be stored with no clientId field at all and looked
+	// up via `ismissing(@clientId)`. Stamp the sentinel so the read path can
+	// probe `@clientId:{global}` instead — a posting-list intersection is
+	// orders of magnitude cheaper than ismissing over a large rule set.
+	// Rules with a real clientId are untouched.
+	if (record.clientId === undefined) {
+		record.clientId = GLOBAL_CLIENT_SCOPE_SENTINEL;
+	}
+	return record;
+};
 
 export class DummyRedisRulesWriter implements AccessRulesWriter {
 	constructor(private readonly logger: Logger) {}

package/src/rule.ts

@@ -18,6 +18,18 @@ export enum AccessPolicyType {
 	Restrict = "restrict",
 }
 
+// Sentinel stamped on the Redis `clientId` field for rules that would
+// otherwise store undefined (i.e. global rules). Lets the read path
+// probe `@clientId:{global}` via the posting-list index instead of the
+// expensive `ismissing(@clientId)` set-difference walk that degrades
+// sharply once the global rule set grows into the 10k+ range. The
+// reader converts it back to `undefined` at parse time so downstream
+// code sees the original AccessRule shape. Kept in this types-only
+// module so both the writer/index side and the parser/input side can
+// import it without pulling in a circular dependency through
+// transformRule.
+export const GLOBAL_CLIENT_SCOPE_SENTINEL = "global";
+
 export type AccessPolicy = {
 	type: AccessPolicyType;
 	captchaType?: CaptchaType;

package/src/ruleInput/policyInput.ts

@@ -14,10 +14,11 @@
 
 import type { AllKeys } from "@prosopo/common";
 import { CaptchaTypeSchema } from "@prosopo/types";
-import { type ZodType, z } from "zod";
+import { z } from "zod";
 import {
 	type AccessPolicy,
 	AccessPolicyType,
+	GLOBAL_CLIENT_SCOPE_SENTINEL,
 	type PolicyScope,
 } from "#policy/rule.js";
 
@@ -57,6 +58,19 @@ export const sanitizeAccessPolicy = (policy: AccessPolicy): AccessPolicy => {
 	return policy;
 };
 
+// `satisfies ZodType<PolicyScope>` is intentionally omitted (matches
+// accessPolicyInput above): the `preprocess` wrapper widens the schema's
+// input type to `unknown`, which fails the `ZodType<T, ZodTypeDef, T>`
+// identity check. The `AllKeys<PolicyScope>` constraint still catches
+// missing-field regressions.
 export const policyScopeInput = z.object({
-	clientId: z.coerce.string().optional(),
-} satisfies AllKeys<PolicyScope>) satisfies ZodType<PolicyScope>;
+	// `getRedisRuleValue` stamps a sentinel string on global rules so the
+	// read-time query can probe `@clientId:{global}` cheaply. Undo the
+	// stamp here so consumers (rankCandidateRules, response payloads,
+	// tests) continue to see `undefined` for global rules — the mongoose
+	// side and the API input side never emit the sentinel.
+	clientId: z.preprocess(
+		(v) => (v === GLOBAL_CLIENT_SCOPE_SENTINEL ? undefined : v),
+		z.coerce.string().optional(),
+	),
+} satisfies AllKeys<PolicyScope>);

package/src/ruleInput/ruleInput.ts

@@ -73,6 +73,12 @@ export type AccessRulesFilterInput = AccessRulesFilter & {
 	policyScopes?: PolicyScope[];
 };
 
+// `satisfies ZodType<AccessRulesFilterInput>` is intentionally omitted:
+// `policyScopeInput.clientId` uses `z.preprocess` to unwrap the Redis
+// `global` sentinel, which widens the input type to `unknown`. The
+// output type is still `AccessRulesFilterInput` (Zod's `_output`); the
+// downstream `DeleteRulesSchema` / `FindRulesSchema` use the relaxed
+// `ZodType<T, ZodTypeDef, unknown>` form for the same reason.
 export const accessRulesFilterInput = z.object({
 	policyScope: policyScopeInput.optional(),
 	policyScopes: z.array(policyScopeInput).optional(),
@@ -85,7 +91,7 @@ export const accessRulesFilterInput = z.object({
 		.default(FilterScopeMatch.Exact),
 	groupId: z.string().optional(),
 	blockOnly: z.boolean().optional(),
-} satisfies AllKeys<AccessRulesFilterInput>) satisfies ZodType<AccessRulesFilterInput>;
+} satisfies AllKeys<AccessRulesFilterInput>);
 
 export const getAccessRuleFiltersFromInput = (
 	filterInput: AccessRulesFilterInput,

package/src/tests/redis/reader/redisRulesSplitQuery.unit.test.ts

@@ -0,0 +1,132 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, it } from "vitest";
+import { buildScopedBlockSubQueries } from "#policy/redis/reader/redisRulesSplitQuery.js";
+
+describe("buildScopedBlockSubQueries", () => {
+	it("emits one sub-query per populated user-scope field", () => {
+		const subs = buildScopedBlockSubQueries(
+			{
+				ja4Hash: "abc",
+				userAgentHash: "def",
+			},
+			"client-A",
+		);
+
+		const kinds = subs.map((s) => s.kind).sort();
+		// Two field probes + one fall-through for "no user-scope
+		// constraint" rules. No IP sub-queries because request has no IP.
+		expect(kinds).toEqual([
+			"field:ja4Hash",
+			"field:userAgentHash",
+			"no-user-scope",
+		]);
+	});
+
+	it("emits both ip-exact and ip-mask sub-queries when request has an IP", () => {
+		const subs = buildScopedBlockSubQueries(
+			{
+				numericIp: 3232235777n, // 192.168.1.1
+			},
+			"client-A",
+		);
+
+		const kinds = subs.map((s) => s.kind);
+		expect(kinds).toContain("ip:exact");
+		expect(kinds).toContain("ip:mask");
+
+		const ipExact = subs.find((s) => s.kind === "ip:exact");
+		expect(ipExact?.query).toContain("@numericIp:[3232235777 3232235777]");
+
+		const ipMask = subs.find((s) => s.kind === "ip:mask");
+		expect(ipMask?.query).toContain("@numericIpMaskMin:[-inf 3232235777]");
+		expect(ipMask?.query).toContain("@numericIpMaskMax:[3232235777 +inf]");
+	});
+
+	it("scopes every sub-query with @type:{block} and @clientId probe", () => {
+		const subs = buildScopedBlockSubQueries({ ja4Hash: "abc" }, "client-A");
+
+		for (const sub of subs) {
+			expect(sub.query).toContain("@type:{block}");
+			// Every sub-query must include the client-or-global scope
+			// probe. `@clientId:{client-A}` matches client-scoped rules;
+			// `@clientId:{global}` matches new-format global rules;
+			// `ismissing(@clientId)` matches legacy pre-sentinel rules.
+			expect(sub.query).toMatch(/@clientId:\{client-A\}/);
+			expect(sub.query).toMatch(/@clientId:\{global\}/);
+			expect(sub.query).toMatch(/ismissing\(@clientId\)/);
+		}
+	});
+
+	it("skips the client-specific probe when no clientId is passed", () => {
+		const subs = buildScopedBlockSubQueries({ ja4Hash: "abc" }, undefined);
+
+		for (const sub of subs) {
+			// No client-scoped probe — request is scoped to global rules
+			// only. `global` sentinel and `ismissing()` fallback remain.
+			expect(sub.query).toMatch(/@clientId:\{global\}/);
+			expect(sub.query).toMatch(/ismissing\(@clientId\)/);
+		}
+	});
+
+	it("emits a no-user-scope fall-through query with ismissing() over every user-scope field", () => {
+		const subs = buildScopedBlockSubQueries({ ja4Hash: "abc" }, "client-A");
+
+		const fallThrough = subs.find((s) => s.kind === "no-user-scope");
+		expect(fallThrough).toBeDefined();
+		// Every user-scope field must be constrained as missing so the
+		// probe returns only rules that are truly client-wide blocks
+		// (no user-scope constraint at all).
+		for (const field of [
+			"userId",
+			"ja4Hash",
+			"headersHash",
+			"userAgentHash",
+			"headHash",
+			"coords",
+			"countryCode",
+			"asn",
+			"numericIp",
+			"numericIpMaskMin",
+			"numericIpMaskMax",
+		]) {
+			expect(fallThrough?.query).toContain(`ismissing(@${field})`);
+		}
+	});
+
+	it("uses NUMERIC range syntax for asn, not TAG syntax", () => {
+		const subs = buildScopedBlockSubQueries({ asn: 205016 }, "client-A");
+
+		const asnSub = subs.find((s) => s.kind === "field:asn");
+		expect(asnSub).toBeDefined();
+		// asn is indexed as NUMERIC; TAG syntax (@asn:{...}) would
+		// silently fail to match. Must use range syntax.
+		expect(asnSub?.query).toContain("@asn:[205016 205016]");
+		expect(asnSub?.query).not.toContain("@asn:{");
+	});
+
+	it("escapes JSON special characters in coords tag queries", () => {
+		const subs = buildScopedBlockSubQueries(
+			{ coords: "[[[100,200]]]" },
+			"client-A",
+		);
+
+		const coordsSub = subs.find((s) => s.kind === "field:coords");
+		expect(coordsSub).toBeDefined();
+		// Coords hold JSON with brackets and commas — every one must be
+		// backslash-escaped or the TAG query silently returns no matches.
+		expect(coordsSub?.query).toContain("@coords:{\\[\\[\\[100\\,200\\]\\]\\]}");
+	});
+});