@prosopo/user-access-policy 3.12.14 → 3.12.16

package/src/matchedRule.ts

@@ -0,0 +1,99 @@
+// 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 type { MatchedAccessRule, MatchedRuleCondition } from "@prosopo/types";
+import type { AccessRule } from "#policy/rule.js";
+import {
+	type UserScopeRecordField,
+	getUserScopeRecordFromAccessRuleRecord,
+	userScopeRecordFields,
+} from "#policy/ruleRecord.js";
+import {
+	makeAccessRuleHash,
+	transformAccessRuleIntoRecord,
+} from "#policy/transformRule.js";
+
+// A `coords` polygon serialises to an unbounded JSON string. The audit UI only
+// needs enough to recognise the rule, and the snapshot is copied onto every
+// record the rule acts on, so cap it rather than dragging kilobytes through
+// Mongo on each blocked request.
+const MAX_CONDITION_VALUE_LENGTH = 256;
+
+const toCondition = (
+	field: UserScopeRecordField,
+	value: unknown,
+): MatchedRuleCondition | undefined => {
+	if (value === undefined || value === null) return undefined;
+	// `asn` is a number on the rule; every other scope field is a string.
+	const asString = typeof value === "string" ? value : String(value);
+	if (asString.length === 0) return undefined;
+	return asString.length > MAX_CONDITION_VALUE_LENGTH
+		? {
+				field,
+				value: `${asString.slice(0, MAX_CONDITION_VALUE_LENGTH)}…`,
+				truncated: true,
+			}
+		: { field, value: asString };
+};
+
+/**
+ * Derive the rule's populated scope fields in record form.
+ *
+ * Goes through `transformAccessRuleIntoRecord` so the IP triple collapses back
+ * to the human-readable `ip` / `ipMask` the operator originally typed, rather
+ * than the numeric range the matcher works in, and so the field names match
+ * the vocabulary the portal's Access Control page already labels conditions
+ * with (`ip`, `ipMask`, `userAgent`, `ja4Hash`, …).
+ */
+const deriveConditions = (rule: AccessRule): MatchedRuleCondition[] => {
+	let scope: Partial<Record<UserScopeRecordField, unknown>>;
+	try {
+		scope = getUserScopeRecordFromAccessRuleRecord(
+			transformAccessRuleIntoRecord(rule),
+		);
+	} catch {
+		// Never let audit bookkeeping break enforcement. A rule shape the
+		// record transform rejects (or an IP range cidr-calc can't express)
+		// still blocks — it just describes itself without conditions.
+		return [];
+	}
+
+	const conditions: MatchedRuleCondition[] = [];
+	for (const field of userScopeRecordFields) {
+		const condition = toCondition(field, scope[field]);
+		if (condition) {
+			conditions.push(condition);
+		}
+	}
+	return conditions;
+};
+
+/**
+ * Snapshot a matched rule for persistence alongside the request it acted on.
+ *
+ * Total function: every rule shape yields a value, so callers can inline it
+ * into a record literal without a try/catch of their own.
+ */
+export const describeMatchedRule = (rule: AccessRule): MatchedAccessRule => ({
+	ruleHash: makeAccessRuleHash(rule),
+	policyType: rule.type,
+	conditions: deriveConditions(rule),
+	...(rule.description !== undefined && { description: rule.description }),
+	...(rule.captchaType !== undefined && { captchaType: rule.captchaType }),
+	...(rule.deferToVerify !== undefined && {
+		deferToVerify: rule.deferToVerify,
+	}),
+	...(rule.groupId !== undefined && { ruleGroupId: rule.groupId }),
+	...(rule.clientId !== undefined && { clientId: rule.clientId }),
+});

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

@@ -0,0 +1,184 @@
+// 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 { CaptchaType, MatchedAccessRuleSchema } from "@prosopo/types";
+import { Address4 } from "ip-address";
+import { describe, expect, it } from "vitest";
+import { describeMatchedRule } from "#policy/matchedRule.js";
+import { AccessPolicyType, type AccessRule } from "#policy/rule.js";
+import { userScopeRecordFields } from "#policy/ruleRecord.js";
+import { makeAccessRuleHash } from "#policy/transformRule.js";
+
+describe("describeMatchedRule", () => {
+	it("carries the policy half of the rule", () => {
+		const rule: AccessRule = {
+			type: AccessPolicyType.Restrict,
+			captchaType: CaptchaType.image,
+			description: "6 rounds for this ASN",
+			deferToVerify: true,
+			clientId: "site-key",
+			groupId: "group-1",
+			ja4Hash: "t13d1516h2_8daaf6152771_b186095e22b6",
+		};
+
+		expect(describeMatchedRule(rule)).toEqual({
+			ruleHash: makeAccessRuleHash(rule),
+			policyType: AccessPolicyType.Restrict,
+			captchaType: CaptchaType.image,
+			description: "6 rounds for this ASN",
+			deferToVerify: true,
+			clientId: "site-key",
+			// `groupId` on the rule is `ruleGroupId` everywhere else — the
+			// portal joins the audit row back to its Access Control entry on
+			// this, so the rename has to happen here.
+			ruleGroupId: "group-1",
+			conditions: [
+				{
+					field: "ja4Hash",
+					value: "t13d1516h2_8daaf6152771_b186095e22b6",
+				},
+			],
+		});
+	});
+
+	it("omits policy fields the rule did not set rather than emitting undefined", () => {
+		const described = describeMatchedRule({ type: AccessPolicyType.Block });
+
+		expect(described).toEqual({
+			ruleHash: makeAccessRuleHash({ type: AccessPolicyType.Block }),
+			policyType: AccessPolicyType.Block,
+			conditions: [],
+		});
+		expect(Object.keys(described)).not.toContain("description");
+		expect(Object.keys(described)).not.toContain("ruleGroupId");
+	});
+
+	it("reports a single IP in the form the operator typed, not the numeric one", () => {
+		const { conditions } = describeMatchedRule({
+			type: AccessPolicyType.Block,
+			numericIp: new Address4("192.0.2.44").bigInt(),
+		});
+
+		expect(conditions).toEqual([{ field: "ip", value: "192.0.2.44" }]);
+	});
+
+	it("collapses an IP range back to its CIDR", () => {
+		const { conditions } = describeMatchedRule({
+			type: AccessPolicyType.Block,
+			numericIpMaskMin: new Address4("198.51.100.64").bigInt(),
+			numericIpMaskMax: new Address4("198.51.100.127").bigInt(),
+		});
+
+		expect(conditions).toEqual([
+			{ field: "ipMask", value: "198.51.100.64/26" },
+		]);
+	});
+
+	it("stringifies a numeric asn", () => {
+		const { conditions } = describeMatchedRule({
+			type: AccessPolicyType.Block,
+			asn: 205016,
+		});
+
+		expect(conditions).toEqual([{ field: "asn", value: "205016" }]);
+	});
+
+	it("reports every populated scope field, in record vocabulary", () => {
+		const { conditions } = describeMatchedRule({
+			type: AccessPolicyType.Block,
+			userId: "user",
+			ja4Hash: "ja4",
+			headersHash: "headers",
+			// Hashed on the rule, but surfaces under the record-side name the
+			// portal labels conditions with.
+			userAgentHash: "ua",
+			headHash: "head",
+			coords: "[[1,2]]",
+			countryCode: "GB",
+			asn: 1,
+			os: "macos",
+			numericIp: new Address4("203.0.113.5").bigInt(),
+		});
+
+		expect(conditions.map((condition) => condition.field)).toEqual([
+			"userId",
+			"ja4Hash",
+			"headersHash",
+			"userAgent",
+			"headHash",
+			"coords",
+			"countryCode",
+			"asn",
+			"os",
+			"ip",
+		]);
+		// Every emitted field is one the portal knows how to label.
+		for (const condition of conditions) {
+			expect(userScopeRecordFields).toContain(condition.field);
+		}
+	});
+
+	it("truncates an oversized coords polygon and flags it", () => {
+		const coords = JSON.stringify([Array.from({ length: 200 }, () => [1, 2])]);
+		const { conditions } = describeMatchedRule({
+			type: AccessPolicyType.Block,
+			coords,
+		});
+
+		const [condition] = conditions;
+		expect(condition?.truncated).toBe(true);
+		expect(condition?.value.length).toBe(257);
+		expect(coords.startsWith(condition?.value.slice(0, -1) ?? "")).toBe(true);
+	});
+
+	it("leaves a value at the cap untruncated", () => {
+		const coords = "x".repeat(256);
+		const { conditions } = describeMatchedRule({
+			type: AccessPolicyType.Block,
+			coords,
+		});
+
+		expect(conditions).toEqual([{ field: "coords", value: coords }]);
+	});
+
+	it("still describes a rule whose scope cannot be transformed", () => {
+		// An inverted mask range makes the record transform throw. Enforcement
+		// must not care: the block still happens, the snapshot just lacks
+		// conditions.
+		const rule: AccessRule = {
+			type: AccessPolicyType.Block,
+			description: "unrepresentable range",
+			numericIpMaskMin: new Address4("198.51.100.200").bigInt(),
+			numericIpMaskMax: new Address4("198.51.100.1").bigInt(),
+		};
+
+		expect(() => describeMatchedRule(rule)).not.toThrow();
+		expect(describeMatchedRule(rule)).toEqual({
+			ruleHash: makeAccessRuleHash(rule),
+			policyType: AccessPolicyType.Block,
+			description: "unrepresentable range",
+			conditions: [],
+		});
+	});
+
+	it("produces a value the persisted schema accepts", () => {
+		const described = describeMatchedRule({
+			type: AccessPolicyType.Restrict,
+			captchaType: CaptchaType.pow,
+			countryCode: "CN",
+		});
+
+		expect(MatchedAccessRuleSchema.safeParse(described).success).toBe(true);
+	});
+});