@prosopo/user-access-policy 3.12.31 → 3.12.33

package/src/.export.ts

@@ -32,6 +32,12 @@ export { describeMatchedRule } from "./matchedRule.js";
 
 export { classifyOs, OS_NAMES, type OsName } from "./classifyOs.js";
 
+export {
+	classifyBrowser,
+	BROWSER_NAMES,
+	type BrowserName,
+} from "./classifyBrowser.js";
+
 export {
 	type AccessRulesFilter,
 	type AccessRulesStorage,

package/src/classifyBrowser.ts

@@ -0,0 +1,77 @@
+// 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.
+
+/**
+ * Kept in step with `@prosopo/decision-machines`' `uaClassify` — as `classifyOs`
+ * is — but defined here because the provider request path cannot depend on that
+ * package.
+ */
+export const BROWSER_NAMES = [
+	"chrome",
+	"safari",
+	"firefox",
+	"edge",
+	"opera",
+	"samsung_internet",
+	"wechat",
+	"facebook",
+	"instagram",
+	"ie",
+	"unknown",
+] as const;
+
+export type BrowserName = (typeof BROWSER_NAMES)[number];
+
+/**
+ * Branch order is load-bearing: every browser below Chrome also carries a
+ * `chrome/` token, and Safari's signature appears in nearly every WebKit UA.
+ *
+ * Reads the User-Agent rather than the `sec-ch-ua` client hint because a client
+ * can simply omit client hints, but stripping the UA breaks far more.
+ */
+export const classifyBrowser = (userAgent: string | undefined): BrowserName => {
+	const ua = (userAgent || "").toLowerCase();
+
+	if (/\bedg(?:e|a|ios)?\//.test(ua)) {
+		return "edge";
+	}
+	if (/samsungbrowser/.test(ua)) {
+		return "samsung_internet";
+	}
+	if (/\bopr\/|opera/.test(ua)) {
+		return "opera";
+	}
+	if (/micromessenger/.test(ua)) {
+		return "wechat";
+	}
+	if (/fban|fbav|fbios/.test(ua)) {
+		return "facebook";
+	}
+	if (/instagram/.test(ua)) {
+		return "instagram";
+	}
+	if (/firefox|fxios/.test(ua)) {
+		return "firefox";
+	}
+	if (/msie|trident/.test(ua)) {
+		return "ie";
+	}
+	if (/\bchrome\/|\bcrios\//.test(ua)) {
+		return "chrome";
+	}
+	if (/safari\//.test(ua)) {
+		return "safari";
+	}
+	return "unknown";
+};

package/src/mongoose/mongooseRuleSchema.ts

@@ -32,6 +32,7 @@ const userAttributesSchema: SchemaDefinition<UserAttributesRecord> = {
 	countryCode: { type: String, required: false },
 	asn: { type: Number, required: false },
 	os: { type: String, required: false },
+	browser: { type: String, required: false },
 } satisfies AllKeys<UserAttributesRecord>;
 
 const userIpSchema: SchemaDefinition<UserIpRecord> = {

package/src/redis/reader/redisRulesReader.ts

@@ -95,6 +95,7 @@ const SPECIFICITY_EXPR = [
 	"exists(@countryCode)",
 	"exists(@asn)",
 	"exists(@os)",
+	"exists(@browser)",
 	"exists(@numericIp)",
 	"exists(@numericIpMaskMin)",
 ].join(" + ");
@@ -135,6 +136,7 @@ const RULE_LOAD_FIELDS = [
 	"@countryCode",
 	"@asn",
 	"@os",
+	"@browser",
 	"@numericIp",
 	"@numericIpMaskMin",
 	"@numericIpMaskMax",
@@ -156,6 +158,7 @@ const readerSpecificity = (rule: AccessRule): number => {
 	if (rule.countryCode !== undefined) score++;
 	if (rule.asn !== undefined) score++;
 	if (rule.os !== undefined) score++;
+	if (rule.browser !== undefined) score++;
 	if (rule.numericIp !== undefined) score++;
 	if (rule.numericIpMaskMin !== undefined) score++;
 	return score;

package/src/redis/reader/redisRulesSplitQuery.ts

@@ -41,6 +41,8 @@ const SCALAR_USER_SCOPE_FIELDS: ReadonlyArray<keyof UserScope> = [
 	"coords",
 	"countryCode",
 	"asn",
+	"os",
+	"browser",
 ];
 
 const ALL_USER_SCOPE_FIELDS: ReadonlyArray<keyof UserScope> = [

package/src/redis/redisRuleIndex.ts

@@ -41,6 +41,7 @@ export const userAttributesRedisSchema: RediSearchSchema = {
 	countryCode: { type: SCHEMA_FIELD_TYPE.TAG, INDEXMISSING: true },
 	asn: { type: SCHEMA_FIELD_TYPE.NUMERIC, INDEXMISSING: true },
 	os: { type: SCHEMA_FIELD_TYPE.TAG, INDEXMISSING: true },
+	browser: { type: SCHEMA_FIELD_TYPE.TAG, INDEXMISSING: true },
 } satisfies AllKeys<UserAttributes>;
 
 export const userScopeRedisSchema: RediSearchSchema = {

package/src/rule.ts

@@ -78,6 +78,7 @@ export type UserAttributes = {
 	// drop/limit requests from a given OS even when the client omits client
 	// hints.
 	os?: string;
+	browser?: string;
 };
 
 export type UserScope = UserAttributes & UserIp;

package/src/ruleInput/userScopeInput.ts

@@ -36,6 +36,7 @@ const userAttributesSchema = z.object({
 	// countryCode: a stale/unknown value just never matches a request rather
 	// than failing the whole rule parse.
 	os: z.coerce.string().optional(),
+	browser: z.coerce.string().optional(),
 } satisfies AllKeys<UserAttributes>) satisfies ZodType<UserAttributes>;
 
 const userAttributesInput = z

package/src/ruleRecord.ts

@@ -32,6 +32,7 @@ export const userAttributesRecordFields = [
 	"countryCode",
 	"asn",
 	"os",
+	"browser",
 ] as const satisfies (keyof UserAttributesRecord)[];
 
 export type UserIpRecord = {

package/src/tests/classifyBrowser.unit.test.ts

@@ -0,0 +1,138 @@
+// 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 {
+	BROWSER_NAMES,
+	type BrowserName,
+	classifyBrowser,
+} from "#policy/classifyBrowser.js";
+
+describe("classifyBrowser", () => {
+	const cases: Array<{ name: string; ua: string; expected: BrowserName }> = [
+		{
+			name: "Chrome on Windows",
+			ua: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+			expected: "chrome",
+		},
+		{
+			name: "Chrome on iOS",
+			ua: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/120.0.0.0 Mobile/15E148 Safari/604.1",
+			expected: "chrome",
+		},
+		{
+			name: "Safari on macOS",
+			ua: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15",
+			expected: "safari",
+		},
+		{
+			name: "Firefox on Linux",
+			ua: "Mozilla/5.0 (X11; Linux x86_64; rv:120.0) Gecko/20100101 Firefox/120.0",
+			expected: "firefox",
+		},
+		{
+			name: "Firefox on iOS",
+			ua: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) FxiOS/120.0 Mobile/15E148 Safari/605.1.15",
+			expected: "firefox",
+		},
+		{
+			name: "Edge on Windows",
+			ua: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0",
+			expected: "edge",
+		},
+		{
+			name: "Opera",
+			ua: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 OPR/106.0.0.0",
+			expected: "opera",
+		},
+		{
+			name: "Samsung Internet",
+			ua: "Mozilla/5.0 (Linux; Android 14; SM-S918B) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/23.0 Chrome/115.0.0.0 Mobile Safari/537.36",
+			expected: "samsung_internet",
+		},
+		{
+			name: "WeChat in-app browser",
+			ua: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 MicroMessenger/8.0.42",
+			expected: "wechat",
+		},
+		{
+			name: "Facebook in-app browser",
+			ua: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 [FBAN/FBIOS;FBAV/442.0.0]",
+			expected: "facebook",
+		},
+		{
+			name: "Instagram in-app browser",
+			ua: "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36 Instagram 310.0.0.0 Android",
+			expected: "instagram",
+		},
+		{
+			name: "Internet Explorer 11",
+			ua: "Mozilla/5.0 (Windows NT 10.0; Trident/7.0; rv:11.0) like Gecko",
+			expected: "ie",
+		},
+	];
+
+	for (const { name, ua, expected } of cases) {
+		it(`classifies ${name} as ${expected}`, () => {
+			expect(classifyBrowser(ua)).toBe(expected);
+		});
+	}
+
+	it("returns 'unknown' for an empty User-Agent", () => {
+		expect(classifyBrowser("")).toBe("unknown");
+	});
+
+	it("returns 'unknown' for an undefined User-Agent", () => {
+		expect(classifyBrowser(undefined)).toBe("unknown");
+	});
+
+	it("returns 'unknown' for an unrecognised User-Agent", () => {
+		expect(classifyBrowser("curl/8.4.0")).toBe("unknown");
+	});
+
+	it("does not classify a Chrome UA as Safari", () => {
+		expect(
+			classifyBrowser(
+				"Mozilla/5.0 (Windows NT 10.0) AppleWebKit/537.36 Chrome/120.0.0.0 Safari/537.36",
+			),
+		).toBe("chrome");
+	});
+
+	it("does not classify an Edge UA as Chrome", () => {
+		expect(
+			classifyBrowser(
+				"Mozilla/5.0 (Windows NT 10.0) AppleWebKit/537.36 Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0",
+			),
+		).toBe("edge");
+	});
+
+	it("does not classify a Samsung Internet UA as Chrome", () => {
+		expect(
+			classifyBrowser(
+				"Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 SamsungBrowser/23.0 Chrome/115.0.0.0 Mobile Safari/537.36",
+			),
+		).toBe("samsung_internet");
+	});
+
+	it("is case-insensitive", () => {
+		expect(classifyBrowser("MOZILLA/5.0 FIREFOX/120.0")).toBe("firefox");
+	});
+
+	it("only ever returns a value from BROWSER_NAMES", () => {
+		const uas = [...cases.map((c) => c.ua), "", "curl/8.4.0", "garbage"];
+		for (const ua of uas) {
+			expect(BROWSER_NAMES).toContain(classifyBrowser(ua));
+		}
+	});
+});

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

@@ -50,7 +50,7 @@ describe("getRulesRedisQuery", () => {
 		const query = getRulesRedisQuery(filter, true);
 
 		expect(query).toBe(
-			"( ( @numericIp:[100 100] | ( @numericIpMaskMin:[-inf 100] @numericIpMaskMax:[100 +inf] ) ) @ja4Hash:{ja4Hash} ismissing(@userAgentHash) ismissing(@userId) ismissing(@headersHash) ismissing(@headHash) ismissing(@coords) ismissing(@countryCode) ismissing(@asn) ismissing(@os) )",
+			"( ( @numericIp:[100 100] | ( @numericIpMaskMin:[-inf 100] @numericIpMaskMax:[100 +inf] ) ) @ja4Hash:{ja4Hash} ismissing(@userAgentHash) ismissing(@userId) ismissing(@headersHash) ismissing(@headHash) ismissing(@coords) ismissing(@countryCode) ismissing(@asn) ismissing(@os) ismissing(@browser) )",
 		);
 	});
 
@@ -126,7 +126,7 @@ describe("getRulesRedisQuery", () => {
 		const query = getRulesRedisQuery(filter, true);
 
 		expect(query).toBe(
-			"( ( @numericIp:[100 100] | ( @numericIpMaskMin:[-inf 100] @numericIpMaskMax:[100 +inf] ) ) @ja4Hash:{ja4Hash} ismissing(@userAgentHash) ismissing(@headersHash) ismissing(@userId) ismissing(@headHash) ismissing(@coords) ismissing(@countryCode) ismissing(@asn) ismissing(@os) )",
+			"( ( @numericIp:[100 100] | ( @numericIpMaskMin:[-inf 100] @numericIpMaskMax:[100 +inf] ) ) @ja4Hash:{ja4Hash} ismissing(@userAgentHash) ismissing(@headersHash) ismissing(@userId) ismissing(@headHash) ismissing(@coords) ismissing(@countryCode) ismissing(@asn) ismissing(@os) ismissing(@browser) )",
 		);
 	});
 
@@ -146,7 +146,7 @@ describe("getRulesRedisQuery", () => {
 		const query = getRulesRedisQuery(filter, true);
 
 		expect(query).toBe(
-			"( @numericIpMaskMin:[-inf 100] @numericIpMaskMax:[200 +inf] @ja4Hash:{ja4Hash} ismissing(@userAgentHash) ismissing(@headersHash) ismissing(@userId) ismissing(@headHash) ismissing(@coords) ismissing(@countryCode) ismissing(@asn) ismissing(@os) )",
+			"( @numericIpMaskMin:[-inf 100] @numericIpMaskMax:[200 +inf] @ja4Hash:{ja4Hash} ismissing(@userAgentHash) ismissing(@headersHash) ismissing(@userId) ismissing(@headHash) ismissing(@coords) ismissing(@countryCode) ismissing(@asn) ismissing(@os) ismissing(@browser) )",
 		);
 	});
 

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

@@ -101,6 +101,8 @@ describe("buildScopedBlockSubQueries", () => {
 			"coords",
 			"countryCode",
 			"asn",
+			"os",
+			"browser",
 			"numericIp",
 			"numericIpMaskMin",
 			"numericIpMaskMax",
@@ -109,6 +111,21 @@ describe("buildScopedBlockSubQueries", () => {
 		}
 	});
 
+	it("emits field probes for the UA-derived os and browser scopes", () => {
+		const subs = buildScopedBlockSubQueries(
+			{ os: "windows", browser: "firefox" },
+			"client-A",
+		);
+
+		// Without its own probe a browser-only rule is reachable only via the
+		// no-user-scope fall-through, sharing that probe's candidate budget.
+		const osSub = subs.find((s) => s.kind === "field:os");
+		expect(osSub?.query).toContain("@os:{windows}");
+
+		const browserSub = subs.find((s) => s.kind === "field:browser");
+		expect(browserSub?.query).toContain("@browser:{firefox}");
+	});
+
 	it("uses NUMERIC range syntax for asn, not TAG syntax", () => {
 		const subs = buildScopedBlockSubQueries({ asn: 205016 }, "client-A");
 

package/src/tests/transformRule.unit.test.ts

@@ -116,6 +116,7 @@ describe("transformRule", () => {
 		countryCode: "US",
 		asn: 205016,
 		os: "macos",
+		browser: "firefox",
 	} satisfies AccessRule;
 
 	it("should transform access rule record into rule", () => {