@prosopo/user-access-policy 3.14.14 → 3.14.16

package/src/classifyOs.ts

@@ -1,74 +0,0 @@
-// 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.
-
-/**
- * The operating systems the classifier can resolve a request to. Kept
- * deliberately in step with the OS vocabulary in
- * `@prosopo/decision-machines`' `uaClassify` (so a routing-rule `osNameIn` and
- * an access-rule `os` agree on the same names), but defined here because the
- * provider / user-access-policy request path cannot depend on the
- * decision-machines package.
- *
- * `unknown` is the catch-all when no signature matches. It is a first-class
- * value so an allow-list ("only let Windows through") can block unrecognised
- * User-Agents instead of silently passing them.
- */
-export const OS_NAMES = [
-	"windows",
-	"macos",
-	"ios",
-	"android",
-	"linux",
-	"unknown",
-] as const;
-
-export type OsName = (typeof OS_NAMES)[number];
-
-/**
- * Classify the operating system from a raw User-Agent string. Pure — no
- * navigator/window/DOM dependence — so it is safe to call on the provider's
- * server-side request path.
- *
- * Detection order matches `uaClassify.classifyUserAgent`: iOS (iphone/ipad/
- * ipod) is tested before the generic mac signature, and Android before Linux,
- * because those User-Agents contain the more general token too. Detection is
- * conservative — anything unrecognised returns `unknown` rather than guessing,
- * so an `os === "ios"` rule never fires on a UA we don't understand.
- *
- * The classification is driven off the full User-Agent rather than the
- * `sec-ch-ua-platform` client hint on purpose: a client can simply omit client
- * hints, but stripping the User-Agent breaks far more, so the UA is the more
- * reliable signal for an OS-restriction rule that is meant to be hard to
- * bypass.
- */
-export const classifyOs = (userAgent: string | undefined): OsName => {
-	const ua = (userAgent || "").toLowerCase();
-
-	if (/iphone|ipad|ipod/.test(ua)) {
-		return "ios";
-	}
-	if (/android/.test(ua)) {
-		return "android";
-	}
-	if (/windows/.test(ua)) {
-		return "windows";
-	}
-	if (/macintosh|mac os/.test(ua)) {
-		return "macos";
-	}
-	if (/linux/.test(ua)) {
-		return "linux";
-	}
-	return "unknown";
-};

package/src/headerMatch.ts

@@ -1,180 +0,0 @@
-// 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/matchedRule.ts

@@ -1,99 +0,0 @@
-// 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/mongoose/.export.ts

@@ -1,15 +0,0 @@
-// 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.
-
-export { accessRuleMongooseSchema } from "./mongooseRuleSchema.js";

package/src/mongoose/mongooseRuleSchema.ts

@@ -1,75 +0,0 @@
-// 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 { AllKeys, Keys } from "@prosopo/common";
-import type { SchemaDefinition } from "mongoose";
-import type { AccessPolicy, PolicyScope } from "#policy/rule.js";
-import type {
-	AccessRuleRecord,
-	UserAttributesRecord,
-	UserIpRecord,
-	UserScopeRecord,
-} from "#policy/ruleRecord.js";
-
-const userAttributesSchema: SchemaDefinition<UserAttributesRecord> = {
-	userId: { type: String, required: false },
-	ja4Hash: { type: String, required: false },
-	userAgent: { type: String, required: false },
-	headersHash: { type: String, required: false },
-	headHash: { type: String, required: false },
-	coords: { type: String, required: false },
-	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 },
-	webBotAuthAgent: { type: String, required: false },
-} satisfies AllKeys<UserAttributesRecord>;
-
-const userIpSchema: SchemaDefinition<UserIpRecord> = {
-	ip: { type: String, required: false },
-	ipMask: { type: String, required: false },
-} satisfies AllKeys<UserIpRecord>;
-
-const userScopeSchema: SchemaDefinition<UserScopeRecord> = {
-	...userAttributesSchema,
-	...userIpSchema,
-} satisfies Keys<UserScopeRecord>;
-
-const policyScopeSchema: SchemaDefinition<PolicyScope> = {
-	clientId: { type: String, required: false },
-} satisfies AllKeys<PolicyScope>;
-
-const accessPolicySchema: SchemaDefinition<AccessPolicy> = {
-	type: { type: String, required: true },
-	captchaType: { type: String, required: false },
-	description: { type: String, required: false },
-	solvedImagesCount: { type: Number, required: false },
-	imageThreshold: { type: Number, required: false },
-	powDifficulty: { type: Number, required: false },
-	unsolvedImagesCount: { type: Number, required: false },
-	frictionlessScore: { type: Number, required: false },
-	deferToVerify: { type: Boolean, required: false },
-	messageKey: { type: String, required: false },
-} satisfies AllKeys<AccessPolicy>;
-
-export const accessRuleMongooseSchema: SchemaDefinition<AccessRuleRecord> = {
-	...accessPolicySchema,
-	...policyScopeSchema,
-	...userScopeSchema,
-	ruleGroupId: { type: String, required: false },
-} satisfies Keys<AccessRuleRecord>;

package/src/redis/.export.ts

@@ -1,17 +0,0 @@
-// 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.
-
-export { createRedisAccessRulesStorage } from "./redisRulesStorage.js";
-
-export { accessRulesRedisIndex } from "./redisRuleIndex.js";

package/src/redis/reader/redisAggregate.ts

@@ -1,157 +0,0 @@
-// 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 { Logger } from "@prosopo/logger";
-import type { FtAggregateWithCursorOptions } from "@redis/search/dist/lib/commands/AGGREGATE_WITHCURSOR.js";
-import type { RedisClientType } from "redis";
-import { z } from "zod";
-import { REDIS_QUERY_DIALECT } from "#policy/redis/reader/redisRulesQuery.js";
-import {
-	REDIS_BATCH_SIZE,
-	parseRedisRecords,
-} from "#policy/redis/redisClient.js";
-import { ACCESS_RULES_REDIS_INDEX_NAME } from "#policy/redis/redisRuleIndex.js";
-
-// Bounded-cap variant of `aggregateRedisKeys` for hot-path sub-queries.
-// Uses FT.SEARCH NOCONTENT rather than FT.AGGREGATE + LOAD @__key so the
-// reply is a flat `[total, key1, key2, ...]` list decoded by
-// `SEARCH_NOCONTENT.transformReply`, never a nested tuples array. That
-// side-steps a crash in `@redis/client` 5.x where a `null` tuple returned
-// by the RediSearch coordinator (seen consistently on the split-query
-// ja4Hash probes in prod — several thousand per hour of
-// `TypeError: Cannot read properties of null (reading 'length')`) makes
-// `transformTuplesReply` throw and the whole sub-query resolve empty.
-// Cap fits in a single call because callers pass a small `maxKeys`
-// (SPLIT_MAX_CANDIDATES_PER_SUB, currently 500) — no cursor needed.
-export const searchRedisKeysBounded = async (
-	client: RedisClientType,
-	query: string,
-	maxKeys: number,
-): Promise<string[]> => {
-	const reply = await client.ft.searchNoContent(
-		ACCESS_RULES_REDIS_INDEX_NAME,
-		query,
-		{
-			DIALECT: REDIS_QUERY_DIALECT,
-			LIMIT: { from: 0, size: maxKeys },
-		},
-	);
-
-	return reply.documents;
-};
-
-// aggregation is used for cases when we need to get "unlimited" search results
-export const aggregateRedisKeys = async (
-	client: RedisClientType,
-	query: string,
-	logger: Logger,
-	batchHandler?: (keys: string[]) => Promise<void>,
-	maxKeys?: number,
-): Promise<string[]> => {
-	const keyField = "__key";
-
-	const recordSchema = z.object({
-		// it's a reserved name for the record key
-		[keyField]: z.string(),
-	});
-
-	const foundKeys: string[] = [];
-	let stopRequested = false;
-
-	const addRecordKeys = async (records: object[]) => {
-		if (stopRequested) {
-			return;
-		}
-
-		const parsedRecords = parseRedisRecords(records, recordSchema, logger);
-
-		const recordKeys = parsedRecords.map((record) => record[keyField]);
-
-		if (batchHandler) {
-			await batchHandler(recordKeys);
-		} else {
-			if (
-				maxKeys !== undefined &&
-				foundKeys.length + recordKeys.length > maxKeys
-			) {
-				const remaining = Math.max(0, maxKeys - foundKeys.length);
-				foundKeys.push(...recordKeys.slice(0, remaining));
-				stopRequested = true;
-
-				logger.warn(() => ({
-					msg: "Redis aggregation candidate cap hit; truncating result set. This can suppress less-frequent rules and should be investigated.",
-					data: {
-						maxKeys,
-						query,
-					},
-				}));
-				return;
-			}
-
-			foundKeys.push(...recordKeys);
-
-			logger.debug(() => ({
-				msg: "Processed aggregation batch",
-				data: {
-					size: recordKeys.length,
-				},
-			}));
-		}
-	};
-
-	await executeAggregation(
-		client,
-		query,
-		{
-			// #2 is a required option when the 'ismissing()' function is in the query body
-			DIALECT: REDIS_QUERY_DIALECT,
-			COUNT: REDIS_BATCH_SIZE,
-			LOAD: `@${keyField}`,
-		},
-		addRecordKeys,
-		() => stopRequested,
-	);
-
-	return foundKeys;
-};
-
-const executeAggregation = async (
-	client: RedisClientType,
-	query: string,
-	aggregateOptions: FtAggregateWithCursorOptions,
-	handleBatch: (records: object[]) => Promise<void>,
-	shouldStop?: () => boolean,
-): Promise<void> => {
-	const initialReply = await client.ft.aggregateWithCursor(
-		ACCESS_RULES_REDIS_INDEX_NAME,
-		query,
-		aggregateOptions,
-	);
-
-	await handleBatch(initialReply.results);
-
-	let cursor = initialReply.cursor;
-
-	while (0 !== cursor && !shouldStop?.()) {
-		const batchReply = await client.ft.cursorRead(
-			ACCESS_RULES_REDIS_INDEX_NAME,
-			cursor,
-			{ COUNT: aggregateOptions.COUNT },
-		);
-
-		await handleBatch(batchReply.results);
-
-		cursor = batchReply.cursor;
-	}
-};