@prosopo/user-access-policy 3.12.32 → 3.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/user-access-policy",
-	"version": "3.12.32",
+	"version": "3.13.0",
 	"type": "module",
 	"engines": {
 		"node": "^24",
@@ -43,29 +43,29 @@
 		"test": "npm run test:unit && npm run test:integration"
 	},
 	"dependencies": {
-		"@prosopo/api": "4.1.4",
-		"@prosopo/api-route": "2.6.56",
-		"@prosopo/common": "3.1.52",
-		"@prosopo/logger": "2.0.7",
-		"@prosopo/redis-client": "1.0.33",
-		"@prosopo/types": "5.5.3",
-		"@prosopo/util": "3.3.7",
+		"@prosopo/api": "4.1.6",
+		"@prosopo/api-route": "2.6.58",
+		"@prosopo/common": "3.1.54",
+		"@prosopo/logger": "2.0.9",
+		"@prosopo/redis-client": "1.0.35",
+		"@prosopo/types": "5.7.0",
+		"@prosopo/util": "3.3.9",
 		"@redis/search": "5.0.0",
 		"cidr-calc": "1.0.4",
 		"dotenv": "16.4.5",
-		"ip-address": "10.5.0",
+		"ip-address": "10.7.0",
 		"redis": "5.0.0",
 		"zod": "3.23.8"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.12",
-		"@prosopo/util-crypto": "13.5.30",
+		"@prosopo/config": "3.3.14",
+		"@prosopo/util-crypto": "13.5.31",
 		"@types/node": "22.10.2",
 		"fast-glob": "3.3.3",
-		"mongoose": "8.24.1",
+		"mongoose": "9.9.4",
 		"vite": "8.1.5",
-		"vitest": "4.1.10",
-		"yargs": "17.7.2"
+		"vitest": "4.1.11",
+		"yargs": "18.1.0"
 	},
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",

package/src/.export.ts

@@ -32,6 +32,23 @@ export { describeMatchedRule } from "./matchedRule.js";
 
 export { classifyOs, OS_NAMES, type OsName } from "./classifyOs.js";
 
+export {
+	classifyBrowser,
+	BROWSER_NAMES,
+	type BrowserName,
+} from "./classifyBrowser.js";
+
+export {
+	HEADER_OPERATORS,
+	type HeaderOperator,
+	HEADER_RULE_MARKER,
+	isHeaderOperator,
+	evaluateHeaderCondition,
+	accessRuleHeaderMatches,
+	encodeHeaderValueList,
+	decodeHeaderValueList,
+} from "./headerMatch.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/headerMatch.ts

@@ -0,0 +1,180 @@
+// 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.
+
+/**
+ * Operators for an access rule's arbitrary-header condition.
+ *
+ * `equals` / `contains` are the deny-list operators (block when the request's
+ * header matches). `notEquals` / `notContains` are their allow-list negations
+ * (block when the request's header does NOT match — including when the header
+ * is absent), so an allow-list card that says "only let requests with header X
+ * through" desugars to `notEquals` / `notContains` Block rules, exactly the way
+ * the OS allow-list desugars to Block rules on the complement.
+ *
+ * `notEqualsAny` / `notContainsAny` are the multi-value form of those two: the
+ * rule's `headerValue` holds a list (see `encodeHeaderValueList`) and the rule
+ * blocks unless the request's header matches *one of* the listed values. They
+ * exist because an allow-list over several values of the SAME header cannot be
+ * expressed as several single-value rules — each rule fires independently, so
+ * `notEquals ios` + `notEquals android` blocks both an iOS and an Android
+ * request. One rule holding both values is the only way to get the "any of"
+ * semantics the allow-list needs.
+ */
+export const HEADER_OPERATORS = [
+	"equals",
+	"contains",
+	"notEquals",
+	"notContains",
+	"notEqualsAny",
+	"notContainsAny",
+] as const;
+
+export type HeaderOperator = (typeof HEADER_OPERATORS)[number];
+
+export const isHeaderOperator = (
+	value: string | undefined,
+): value is HeaderOperator =>
+	value !== undefined &&
+	(HEADER_OPERATORS as ReadonlyArray<string>).includes(value);
+
+/**
+ * Sentinel value carried both on every request's user scope (see
+ * `getRequestUserScope`) and on every header-restriction rule. Header rules
+ * match on data (`headerName` / `headerValue` / `headerOperator`) that Redis
+ * cannot evaluate — substring `contains` and per-rule operators aren't
+ * expressible as a TAG query, and an allow-list rule must still fire on a
+ * request that OMITS the target header, so candidate selection can't key off
+ * header presence. Redis returns header rules via the reader's
+ * `no-user-scope` fall-through probe (they constrain none of the indexed
+ * scope dimensions); this marker is what keeps them candidates through the
+ * JS-side `ruleApplies` scalar check, which would otherwise drop a rule
+ * carrying a scope field the request lacks. The concrete condition is then
+ * checked by `accessRuleHeaderMatches`.
+ */
+export const HEADER_RULE_MARKER = "1";
+
+/**
+ * Encode the value list carried by a multi-value operator (`notEqualsAny` /
+ * `notContainsAny`) into the single `headerValue` string an access rule can
+ * store. JSON rather than a delimiter because header values are arbitrary
+ * text — any separator we picked could legitimately occur inside a value.
+ */
+export const encodeHeaderValueList = (values: ReadonlyArray<string>): string =>
+	JSON.stringify(values);
+
+/**
+ * Inverse of {@link encodeHeaderValueList}, tolerant of rules written by hand
+ * (e.g. via the access-policy CLI) that carry a single literal value instead of
+ * an encoded list.
+ *
+ * Returns `undefined` for a value that looks list-encoded but isn't usable — an
+ * empty list, a non-array, non-string members, or malformed JSON. Callers treat
+ * that as a malformed rule and decline to fire it, so a garbled list can't
+ * silently block all traffic.
+ */
+export const decodeHeaderValueList = (value: string): string[] | undefined => {
+	if (!value.trimStart().startsWith("[")) {
+		// Not list-encoded: treat the whole string as a one-value list.
+		return [value];
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		return undefined;
+	}
+	if (
+		!Array.isArray(parsed) ||
+		parsed.length === 0 ||
+		!parsed.every((entry): entry is string => typeof entry === "string")
+	) {
+		return undefined;
+	}
+	return parsed;
+};
+
+/**
+ * Evaluate a single header condition against a request's headers. Returns
+ * `true` when the condition is satisfied — i.e. when a Block rule carrying it
+ * should fire for this request.
+ *
+ * `headers` is expected to be keyed by lower-cased header name (HTTP header
+ * names are case-insensitive); `headerName` is lower-cased here defensively.
+ * The negated operators treat an absent header as "not matching the value",
+ * which is what makes an allow-list block a request that drops the header.
+ */
+export const evaluateHeaderCondition = (
+	headerName: string,
+	operator: HeaderOperator,
+	value: string,
+	headers: Record<string, string>,
+): boolean => {
+	const actual = headers[headerName.toLowerCase()];
+	switch (operator) {
+		case "equals":
+			return actual !== undefined && actual === value;
+		case "contains":
+			return actual?.includes(value) ?? false;
+		case "notEquals":
+			return actual === undefined || actual !== value;
+		case "notContains":
+			return actual === undefined || !actual.includes(value);
+		case "notEqualsAny": {
+			const values = decodeHeaderValueList(value);
+			if (values === undefined) {
+				return false;
+			}
+			return actual === undefined || !values.includes(actual);
+		}
+		case "notContainsAny": {
+			const values = decodeHeaderValueList(value);
+			if (values === undefined) {
+				return false;
+			}
+			return (
+				actual === undefined ||
+				!values.some((candidate) => actual.includes(candidate))
+			);
+		}
+	}
+};
+
+/**
+ * Whether a rule's header condition (if any) is satisfied by the request's
+ * headers. A rule with no `headerName` carries no header constraint, so it is
+ * treated as satisfied and the rule's other dimensions decide the match. A
+ * rule with a `headerName` but an unrecognised operator is malformed and never
+ * matches (fail-safe: a garbled rule must not silently block traffic).
+ */
+export const accessRuleHeaderMatches = (
+	rule: {
+		headerName?: string;
+		headerValue?: string;
+		headerOperator?: string;
+	},
+	headers: Record<string, string>,
+): boolean => {
+	if (rule.headerName === undefined) {
+		return true;
+	}
+	if (!isHeaderOperator(rule.headerOperator)) {
+		return false;
+	}
+	return evaluateHeaderCondition(
+		rule.headerName,
+		rule.headerOperator,
+		rule.headerValue ?? "",
+		headers,
+	);
+};

package/src/mongoose/mongooseRuleSchema.ts

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

package/src/redis/reader/redisRulesReader.ts

@@ -95,6 +95,10 @@ const SPECIFICITY_EXPR = [
 	"exists(@countryCode)",
 	"exists(@asn)",
 	"exists(@os)",
+	"exists(@browser)",
+	// A header rule is one logical dimension: only the sentinel counts toward
+	// specificity, not the name/value/operator triple it also carries.
+	"exists(@headerMatch)",
 	"exists(@numericIp)",
 	"exists(@numericIpMaskMin)",
 ].join(" + ");
@@ -135,6 +139,11 @@ const RULE_LOAD_FIELDS = [
 	"@countryCode",
 	"@asn",
 	"@os",
+	"@browser",
+	"@headerMatch",
+	"@headerName",
+	"@headerValue",
+	"@headerOperator",
 	"@numericIp",
 	"@numericIpMaskMin",
 	"@numericIpMaskMax",
@@ -156,6 +165,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,20 @@ 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 },
+	// Header-restriction fields. NONE of these are queried on the hot path:
+	// the split-query builder probes neither `headerMatch` nor the
+	// name/value/operator triple, and a header rule populates none of the
+	// fields that builder does probe, so it is returned by the `no-user-scope`
+	// fall-through probe (the same route `os` rules take) and the concrete
+	// condition is evaluated in code by `accessRuleHeaderMatches`. They are
+	// indexed to satisfy the schema exhaustiveness check, and `headerMatch`
+	// additionally gates candidacy JS-side in `ruleApplies` and scores one
+	// specificity point in the reader's SPECIFICITY_EXPR.
+	headerMatch: { type: SCHEMA_FIELD_TYPE.TAG, INDEXMISSING: true },
+	headerName: { type: SCHEMA_FIELD_TYPE.TAG, INDEXMISSING: true },
+	headerValue: { type: SCHEMA_FIELD_TYPE.TAG, INDEXMISSING: true },
+	headerOperator: { type: SCHEMA_FIELD_TYPE.TAG, INDEXMISSING: true },
 } satisfies AllKeys<UserAttributes>;
 
 export const userScopeRedisSchema: RediSearchSchema = {

package/src/rule.ts

@@ -78,6 +78,20 @@ export type UserAttributes = {
 	// drop/limit requests from a given OS even when the client omits client
 	// hints.
 	os?: string;
+	browser?: string;
+	// Arbitrary-header matching (see `headerMatch.ts` and the portal Header
+	// Restriction card). A header rule carries `headerName` + `headerValue` +
+	// `headerOperator`; unlike the other dimensions these are checked in code
+	// against the raw request headers — Redis TAG can't express substring
+	// `contains` or per-rule operators — so they are not part of the Redis
+	// matching query. `headerMatch` is the indexed sentinel (always
+	// `HEADER_RULE_MARKER`) that makes such a rule a matching candidate for
+	// every request, so an allow-list rule still fires on a request that omits
+	// the target header.
+	headerMatch?: string;
+	headerName?: string;
+	headerValue?: string;
+	headerOperator?: string;
 };
 
 export type UserScope = UserAttributes & UserIp;

package/src/ruleInput/userScopeInput.ts

@@ -36,6 +36,14 @@ 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(),
+	// Arbitrary-header matching (see `headerMatch.ts`). `headerMatch` is the
+	// indexed sentinel; name/value/operator are rule data checked in code, not
+	// via the Redis query. Loose `string` like the other tags.
+	headerMatch: z.coerce.string().optional(),
+	headerName: z.coerce.string().optional(),
+	headerValue: z.coerce.string().optional(),
+	headerOperator: z.coerce.string().optional(),
 } satisfies AllKeys<UserAttributes>) satisfies ZodType<UserAttributes>;
 
 const userAttributesInput = z

package/src/ruleRecord.ts

@@ -32,6 +32,11 @@ export const userAttributesRecordFields = [
 	"countryCode",
 	"asn",
 	"os",
+	"browser",
+	"headerMatch",
+	"headerName",
+	"headerValue",
+	"headerOperator",
 ] 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));
+		}
+	});
+});