@prosopo/user-access-policy 3.12.33 → 3.14.0

package/src/rule.ts

@@ -16,6 +16,15 @@ import type { CaptchaType } from "@prosopo/types";
 export enum AccessPolicyType {
 	Block = "block",
 	Restrict = "restrict",
+	// Explicit allow-list: request that matches an Allow rule bypasses the
+	// challenge flow and gets an `authenticated` session (captchaType =
+	// authenticated on the frictionless response). Fires for any qualifying
+	// scope — verified Web Bot Auth agent, allow-listed IP, ja4/ja4_and_ip
+	// match, UA substring, ASN, country. IP-binding on the resulting
+	// session token defends against replay from a different IP. Opt-in per
+	// rule; the operator authors an Allow rule the same way they'd author
+	// a Block or Restrict rule.
+	Allow = "allow",
 }
 
 // Sentinel stamped on the Redis `clientId` field for rules that would
@@ -79,6 +88,26 @@ export type UserAttributes = {
 	// 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;
+	// Canonical Web Bot Auth Signature-Agent URL — e.g.
+	// "https://signatures.openai.com/". Matched at runtime against the
+	// `Signature-Agent` header after RFC 9421 Ed25519 verification succeeds.
+	// Stored as-is like `countryCode` (exact equality after normalisation).
+	// Rules with this field only match requests carrying a valid Web Bot
+	// Auth signature; unverified traffic falls through.
+	webBotAuthAgent?: string;
 };
 
 export type UserScope = UserAttributes & UserIp;

package/src/ruleInput/userScopeInput.ts

@@ -22,6 +22,18 @@ import type { UserAttributesRecord, UserIpRecord } from "#policy/ruleRecord.js";
 
 export type UserAttributesInput = UserAttributes & UserAttributesRecord;
 
+// Cloudflare's Web Bot Auth reference implementation compares Signature-Agent
+// values as URL objects, which are case-insensitive on scheme/host but
+// case-sensitive on path. Store the canonical form so runtime matcher can use
+// plain string equality.
+function normaliseSignatureAgentUrl(raw: string): string {
+	const url = new URL(raw);
+	url.hostname = url.hostname.toLowerCase();
+	url.protocol = url.protocol.toLowerCase();
+	if (url.pathname === "/") url.pathname = "";
+	return url.toString().replace(/\/$/, "");
+}
+
 const userAttributesSchema = z.object({
 	// coerce is used for safety, as e.g., incoming userId can be digital
 	userId: z.coerce.string().optional(),
@@ -37,6 +49,22 @@ const userAttributesSchema = z.object({
 	// 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(),
+	// Web Bot Auth Signature-Agent URL. Normalised at parse time
+	// (lowercase scheme+host, no trailing slash) so the runtime matcher can
+	// use exact string equality against the verified `Signature-Agent`
+	// header value.
+	webBotAuthAgent: z.coerce
+		.string()
+		.url()
+		.transform(normaliseSignatureAgentUrl)
+		.optional(),
 } satisfies AllKeys<UserAttributes>) satisfies ZodType<UserAttributes>;
 
 const userAttributesInput = z

package/src/ruleRecord.ts

@@ -33,6 +33,11 @@ export const userAttributesRecordFields = [
 	"asn",
 	"os",
 	"browser",
+	"headerMatch",
+	"headerName",
+	"headerValue",
+	"headerOperator",
+	"webBotAuthAgent",
 ] as const satisfies (keyof UserAttributesRecord)[];
 
 export type UserIpRecord = {

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

@@ -0,0 +1,350 @@
+// 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 {
+	type HeaderOperator,
+	accessRuleHeaderMatches,
+	decodeHeaderValueList,
+	encodeHeaderValueList,
+	evaluateHeaderCondition,
+	isHeaderOperator,
+} from "#policy/headerMatch.js";
+
+describe("isHeaderOperator", () => {
+	it("accepts the six known operators", () => {
+		for (const op of [
+			"equals",
+			"contains",
+			"notEquals",
+			"notContains",
+			"notEqualsAny",
+			"notContainsAny",
+		]) {
+			expect(isHeaderOperator(op)).toBe(true);
+		}
+	});
+
+	it("rejects unknown / undefined values", () => {
+		expect(isHeaderOperator("startsWith")).toBe(false);
+		expect(isHeaderOperator("")).toBe(false);
+		expect(isHeaderOperator(undefined)).toBe(false);
+	});
+});
+
+describe("evaluateHeaderCondition", () => {
+	const headers: Record<string, string> = {
+		"x-app-version": "1.2.3-beta",
+		"cf-worker": "example.com",
+	};
+
+	const cases: ReadonlyArray<{
+		name: string;
+		op: HeaderOperator;
+		value: string;
+		header: string;
+		expected: boolean;
+	}> = [
+		// equals: present + exact
+		{
+			name: "equals hit",
+			op: "equals",
+			value: "example.com",
+			header: "cf-worker",
+			expected: true,
+		},
+		{
+			name: "equals miss (different value)",
+			op: "equals",
+			value: "evil.com",
+			header: "cf-worker",
+			expected: false,
+		},
+		{
+			name: "equals miss (header absent)",
+			op: "equals",
+			value: "anything",
+			header: "x-missing",
+			expected: false,
+		},
+		// contains: substring
+		{
+			name: "contains hit",
+			op: "contains",
+			value: "beta",
+			header: "x-app-version",
+			expected: true,
+		},
+		{
+			name: "contains miss (no substring)",
+			op: "contains",
+			value: "alpha",
+			header: "x-app-version",
+			expected: false,
+		},
+		{
+			name: "contains miss (header absent)",
+			op: "contains",
+			value: "beta",
+			header: "x-missing",
+			expected: false,
+		},
+		// notEquals: allow-list "equals" — blocks when NOT exactly equal
+		{
+			name: "notEquals blocks a different value",
+			op: "notEquals",
+			value: "example.com",
+			header: "cf-worker",
+			expected: false,
+		},
+		{
+			name: "notEquals lets an exact match through",
+			op: "notEquals",
+			value: "evil.com",
+			header: "cf-worker",
+			expected: true,
+		},
+		{
+			name: "notEquals blocks an absent header",
+			op: "notEquals",
+			value: "secret",
+			header: "x-secret",
+			expected: true,
+		},
+		// notContains: allow-list "contains" — blocks when substring absent
+		{
+			name: "notContains blocks when substring present",
+			op: "notContains",
+			value: "beta",
+			header: "x-app-version",
+			expected: false,
+		},
+		{
+			name: "notContains lets a substring hit through",
+			op: "notContains",
+			value: "alpha",
+			header: "x-app-version",
+			expected: true,
+		},
+		{
+			name: "notContains blocks an absent header",
+			op: "notContains",
+			value: "beta",
+			header: "x-missing",
+			expected: true,
+		},
+	];
+
+	for (const c of cases) {
+		it(c.name, () => {
+			expect(evaluateHeaderCondition(c.header, c.op, c.value, headers)).toBe(
+				c.expected,
+			);
+		});
+	}
+
+	it("matches header names case-insensitively", () => {
+		expect(
+			evaluateHeaderCondition("CF-Worker", "equals", "example.com", headers),
+		).toBe(true);
+	});
+});
+
+describe("accessRuleHeaderMatches", () => {
+	const headers: Record<string, string> = { "x-debug": "1" };
+
+	it("passes trivially when the rule has no header condition", () => {
+		expect(accessRuleHeaderMatches({}, headers)).toBe(true);
+	});
+
+	it("evaluates a well-formed header condition", () => {
+		expect(
+			accessRuleHeaderMatches(
+				{ headerName: "x-debug", headerOperator: "equals", headerValue: "1" },
+				headers,
+			),
+		).toBe(true);
+		expect(
+			accessRuleHeaderMatches(
+				{ headerName: "x-debug", headerOperator: "equals", headerValue: "0" },
+				headers,
+			),
+		).toBe(false);
+	});
+
+	it("never matches a rule with a header name but an invalid operator", () => {
+		expect(
+			accessRuleHeaderMatches(
+				{ headerName: "x-debug", headerOperator: "wat", headerValue: "1" },
+				headers,
+			),
+		).toBe(false);
+	});
+
+	it("treats a missing headerValue as an empty string", () => {
+		// "contains empty string" is always true for a present header.
+		expect(
+			accessRuleHeaderMatches(
+				{ headerName: "x-debug", headerOperator: "contains" },
+				headers,
+			),
+		).toBe(true);
+	});
+});
+
+describe("encode/decodeHeaderValueList", () => {
+	it("round-trips a list of values", () => {
+		const values = ["ios", "android", "web"];
+		expect(decodeHeaderValueList(encodeHeaderValueList(values))).toEqual(
+			values,
+		);
+	});
+
+	it("round-trips values containing the characters a delimiter would break on", () => {
+		const values = ["en-GB,en;q=0.9", 'a"b', "c\\d", "[bracketed]"];
+		expect(decodeHeaderValueList(encodeHeaderValueList(values))).toEqual(
+			values,
+		);
+	});
+
+	it("treats a plain (non list-encoded) value as a one-value list", () => {
+		expect(decodeHeaderValueList("ios")).toEqual(["ios"]);
+		expect(decodeHeaderValueList("")).toEqual([""]);
+	});
+
+	it("rejects a list-shaped value that is not a usable list", () => {
+		expect(decodeHeaderValueList("[")).toBeUndefined();
+		expect(decodeHeaderValueList("[not json]")).toBeUndefined();
+		expect(decodeHeaderValueList("[]")).toBeUndefined();
+		expect(decodeHeaderValueList("[1,2]")).toBeUndefined();
+		expect(decodeHeaderValueList('["ok", null]')).toBeUndefined();
+	});
+});
+
+describe("evaluateHeaderCondition — multi-value allow-list operators", () => {
+	const headers: Record<string, string> = {
+		"x-app": "android",
+		"user-agent": "Mozilla/5.0 (Linux; Android 14) Chrome/120",
+	};
+
+	const allowedApps = encodeHeaderValueList(["ios", "android"]);
+
+	it("does not block a request whose header is one of the allowed values", () => {
+		expect(
+			evaluateHeaderCondition("x-app", "notEqualsAny", allowedApps, headers),
+		).toBe(false);
+		expect(
+			evaluateHeaderCondition(
+				"x-app",
+				"notEqualsAny",
+				encodeHeaderValueList(["android"]),
+				headers,
+			),
+		).toBe(false);
+	});
+
+	it("blocks a request whose header matches none of the allowed values", () => {
+		expect(
+			evaluateHeaderCondition(
+				"x-app",
+				"notEqualsAny",
+				encodeHeaderValueList(["ios", "web"]),
+				headers,
+			),
+		).toBe(true);
+	});
+
+	it("blocks a request that omits the header entirely", () => {
+		expect(
+			evaluateHeaderCondition(
+				"x-missing",
+				"notEqualsAny",
+				allowedApps,
+				headers,
+			),
+		).toBe(true);
+		expect(
+			evaluateHeaderCondition(
+				"x-missing",
+				"notContainsAny",
+				allowedApps,
+				headers,
+			),
+		).toBe(true);
+	});
+
+	it("matches a substring of the header for notContainsAny", () => {
+		expect(
+			evaluateHeaderCondition(
+				"user-agent",
+				"notContainsAny",
+				encodeHeaderValueList(["Android", "iPhone"]),
+				headers,
+			),
+		).toBe(false);
+		expect(
+			evaluateHeaderCondition(
+				"user-agent",
+				"notContainsAny",
+				encodeHeaderValueList(["iPhone", "Windows"]),
+				headers,
+			),
+		).toBe(true);
+	});
+
+	it("is exact for notEqualsAny — a substring is not a match", () => {
+		expect(
+			evaluateHeaderCondition(
+				"x-app",
+				"notEqualsAny",
+				encodeHeaderValueList(["droid"]),
+				headers,
+			),
+		).toBe(true);
+	});
+
+	it("never fires on a malformed value list, rather than blocking everything", () => {
+		for (const operator of ["notEqualsAny", "notContainsAny"] as const) {
+			expect(evaluateHeaderCondition("x-app", operator, "[]", headers)).toBe(
+				false,
+			);
+			expect(
+				evaluateHeaderCondition("x-missing", operator, "[bad", headers),
+			).toBe(false);
+		}
+	});
+
+	it("is reachable through accessRuleHeaderMatches", () => {
+		expect(
+			accessRuleHeaderMatches(
+				{
+					headerName: "X-App",
+					headerOperator: "notEqualsAny",
+					headerValue: allowedApps,
+				},
+				headers,
+			),
+		).toBe(false);
+		expect(
+			accessRuleHeaderMatches(
+				{
+					headerName: "X-App",
+					headerOperator: "notEqualsAny",
+					headerValue: encodeHeaderValueList(["ios"]),
+				},
+				headers,
+			),
+		).toBe(true);
+	});
+});

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) ismissing(@browser) )",
+			"( ( @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) ismissing(@headerMatch) ismissing(@headerName) ismissing(@headerValue) ismissing(@headerOperator) ismissing(@webBotAuthAgent) )",
 		);
 	});
 
@@ -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) ismissing(@browser) )",
+			"( ( @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) ismissing(@headerMatch) ismissing(@headerName) ismissing(@headerValue) ismissing(@headerOperator) ismissing(@webBotAuthAgent) )",
 		);
 	});
 
@@ -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) ismissing(@browser) )",
+			"( @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) ismissing(@headerMatch) ismissing(@headerName) ismissing(@headerValue) ismissing(@headerOperator) ismissing(@webBotAuthAgent) )",
 		);
 	});
 

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

@@ -117,6 +117,11 @@ describe("transformRule", () => {
 		asn: 205016,
 		os: "macos",
 		browser: "firefox",
+		headerMatch: "1",
+		headerName: "x-test",
+		headerValue: "test",
+		headerOperator: "equals",
+		webBotAuthAgent: "https://signatures.openai.com",
 	} satisfies AccessRule;
 
 	it("should transform access rule record into rule", () => {