@prosopo/user-access-policy 3.6.0 → 3.7.12

package/src/api/write/rehashRules.ts

@@ -0,0 +1,85 @@
+// 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 ApiEndpoint,
+	type ApiEndpointResponse,
+	ApiEndpointResponseStatus,
+} from "@prosopo/api-route";
+import type { Logger } from "@prosopo/logger";
+import type { AccessRulesStorage } from "#policy/rulesStorage.js";
+
+export class RehashRulesEndpoint implements ApiEndpoint<undefined> {
+	public constructor(
+		private readonly accessRulesStorage: AccessRulesStorage,
+		private readonly logger: Logger,
+	) {}
+
+	public getRequestArgsSchema(): undefined {}
+
+	async processRequest(logger?: Logger): Promise<ApiEndpointResponse> {
+		const log = logger ?? this.logger;
+		await this.accessRulesStorage.fetchAllRuleIds(async (ruleIds: string[]) => {
+			log.info(() => ({
+				msg: "Fetched rule ids batch",
+				data: {
+					count: ruleIds.length,
+					ruleIds,
+				},
+			}));
+
+			const ruleEntries = await this.accessRulesStorage.fetchRules(ruleIds);
+
+			log.info(() => ({
+				msg: "Fetched rules",
+				data: {
+					count: ruleEntries.length,
+				},
+			}));
+
+			if (ruleEntries.length !== ruleIds.length) {
+				log.warn(() => ({
+					msg: "Fetched rules count is not equal to the requested count",
+					data: {
+						fetchedCount: ruleEntries.length,
+						requestedCount: ruleIds.length,
+					},
+				}));
+			}
+
+			await this.accessRulesStorage.deleteRules(ruleIds);
+
+			log.info(() => ({
+				msg: "Deleted rules",
+				data: {
+					count: ruleIds.length,
+				},
+			}));
+
+			await this.accessRulesStorage.insertRules(ruleEntries);
+
+			log.info(() => ({
+				msg: "Inserted rules",
+				data: {
+					count: ruleEntries.length,
+				},
+			}));
+		});
+
+		return {
+			status: ApiEndpointResponseStatus.SUCCESS,
+			data: {},
+		};
+	}
+}

package/src/mongoose/.export.ts

@@ -0,0 +1,15 @@
+// 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

@@ -0,0 +1,65 @@
+// 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 },
+} 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 },
+} satisfies AllKeys<AccessPolicy>;
+
+export const accessRuleMongooseSchema: SchemaDefinition<AccessRuleRecord> = {
+	...accessPolicySchema,
+	...policyScopeSchema,
+	...userScopeSchema,
+	ruleGroupId: { type: String, required: false },
+} satisfies Keys<AccessRuleRecord>;

package/src/redis/.export.ts

@@ -0,0 +1,17 @@
+// 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

@@ -0,0 +1,103 @@
+// 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";
+
+// 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>,
+): Promise<string[]> => {
+	const keyField = "__key";
+
+	const recordSchema = z.object({
+		// it's a reserved name for the record key
+		[keyField]: z.string(),
+	});
+
+	const foundKeys: string[] = [];
+
+	const addRecordKeys = async (records: object[]) => {
+		const parsedRecords = parseRedisRecords(records, recordSchema, logger);
+
+		const recordKeys = parsedRecords.map((record) => record[keyField]);
+
+		if (batchHandler) {
+			await batchHandler(recordKeys);
+		} else {
+			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,
+	);
+
+	return foundKeys;
+};
+
+const executeAggregation = async (
+	client: RedisClientType,
+	query: string,
+	aggregateOptions: FtAggregateWithCursorOptions,
+	handleBatch: (records: object[]) => Promise<void>,
+): 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) {
+		const batchReply = await client.ft.cursorRead(
+			ACCESS_RULES_REDIS_INDEX_NAME,
+			cursor,
+			{ COUNT: aggregateOptions.COUNT },
+		);
+
+		await handleBatch(batchReply.results);
+
+		cursor = batchReply.cursor;
+	}
+};

package/src/redis/reader/redisRulesQuery.ts

@@ -0,0 +1,217 @@
+// 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 { PolicyScope, UserIp, UserScope } from "#policy/rule.js";
+import { userScopeSchema } from "#policy/ruleInput/userScopeInput.js";
+import {
+	type AccessRulesFilter,
+	FilterScopeMatch,
+} from "#policy/rulesStorage.js";
+
+type QueryBuilder = (value: unknown, scope: UserIp) => string;
+
+/**
+ * Escapes special characters for Redis TAG field queries.
+ * Redis TAG fields treat these characters as special and they must be escaped with a backslash.
+ */
+const escapeTagValue = (value: string): string => {
+	// Characters that need escaping in Redis TAG queries
+	return value.replace(/([,.<>{}\[\]"':;!@#$%^&*()\-+=~|/\\])/g, "\\$1");
+};
+
+// #2 is a required option when the 'ismissing()' function is in the query body
+export const REDIS_QUERY_DIALECT = 2;
+
+const userIpQueries: Record<keyof UserIp, QueryBuilder> = {
+	numericIp: (value, scope) => {
+		if (undefined !== value) {
+			return `( @numericIp:[${value} ${value}] | ( @numericIpMaskMin:[-inf ${value}] @numericIpMaskMax:[${value} +inf] ) )`;
+		}
+		// Only emit ismissing(@numericIp) if ranges are also not present
+		if (
+			scope.numericIpMaskMin === undefined &&
+			scope.numericIpMaskMax === undefined
+		) {
+			return "ismissing(@numericIp) ismissing(@numericIpMaskMin) ismissing(@numericIpMaskMax)";
+		}
+		// Else, let ranges handle it
+		return "";
+	},
+	numericIpMaskMin: (value, scope) => {
+		if (scope.numericIp !== undefined) {
+			return ""; // handled by numericIp
+		}
+		// When all IP fields are undefined, numericIp handler already emits all ismissing clauses
+		if (value === undefined && scope.numericIpMaskMax === undefined) {
+			return "";
+		}
+		return value !== undefined
+			? `@numericIpMaskMin:[-inf ${value}]`
+			: "ismissing(@numericIpMaskMin)";
+	},
+	numericIpMaskMax: (value, scope) => {
+		if (scope.numericIp !== undefined) {
+			return ""; // handled by numericIp
+		}
+		// When all IP fields are undefined, numericIp handler already emits all ismissing clauses
+		if (value === undefined && scope.numericIpMaskMin === undefined) {
+			return "";
+		}
+		return value !== undefined
+			? `@numericIpMaskMax:[${value} +inf]`
+			: "ismissing(@numericIpMaskMax)";
+	},
+};
+
+const getUserScopeQuery = (
+	userScope: UserScope,
+	FilterScopeMatchType: FilterScopeMatch | undefined,
+	matchingFieldsOnly: boolean,
+): string => {
+	let scopeEntries = Object.entries(userScope) as Array<
+		[keyof UserScope, unknown]
+	>;
+	let scopeJoinType = " ";
+
+	// skip fields with undefined values if in greedy mode and set operator to OR
+	if (FilterScopeMatchType === FilterScopeMatch.Greedy) {
+		scopeEntries = scopeEntries.filter(
+			([_, value]) => value !== undefined,
+		) as Array<[keyof UserScope, unknown]>;
+		scopeJoinType = " | ";
+	}
+
+	if (matchingFieldsOnly) {
+		const scopeMap = new Map<keyof UserScope, unknown>(scopeEntries);
+
+		// If numericIp is explicitly undefined, set both range fields to undefined
+		if (scopeMap.has("numericIp") && scopeMap.get("numericIp") === undefined) {
+			scopeMap.set("numericIpMaskMin", undefined);
+			scopeMap.set("numericIpMaskMax", undefined);
+		}
+
+		// Ensure all expected fields are accounted for
+		for (const name of Object.keys(userScopeSchema.shape) as Array<
+			keyof UserScope
+		>) {
+			if (!scopeMap.has(name)) {
+				scopeMap.set(name, undefined);
+			}
+		}
+
+		scopeEntries = [...scopeMap.entries()];
+	}
+
+	const scopeObj = Object.fromEntries(scopeEntries) as Partial<UserScope>;
+
+	return scopeEntries
+		.map(([scopeFieldName, scopeFieldValue]) =>
+			getUserScopeFieldQuery(
+				scopeFieldName,
+				scopeFieldValue,
+				FilterScopeMatchType,
+				scopeObj,
+			),
+		)
+		.filter(Boolean)
+		.join(scopeJoinType);
+};
+
+// Fields that may contain special characters requiring escaping in Redis TAG queries
+const FIELDS_REQUIRING_ESCAPE: ReadonlySet<keyof UserScope> = new Set([
+	"coords",
+]);
+
+const getUserScopeFieldQuery = (
+	fieldName: keyof UserScope,
+	fieldValue: unknown,
+	scopeMatch: FilterScopeMatch | undefined,
+	fullScope: Partial<UserScope>,
+): string => {
+	if (fieldName in userIpQueries) {
+		const queryBuilder = userIpQueries[fieldName as keyof UserIp];
+
+		return queryBuilder(fieldValue, fullScope);
+	}
+
+	if (undefined === fieldValue) {
+		return `ismissing(@${fieldName})`;
+	}
+
+	const stringValue = String(fieldValue);
+	// Only escape fields that may contain special characters (like coords with JSON)
+	const queryValue = FIELDS_REQUIRING_ESCAPE.has(fieldName)
+		? escapeTagValue(stringValue)
+		: stringValue;
+
+	return `@${fieldName}:{${queryValue}}`;
+};
+
+const getPolicyScopeQuery = (
+	policyScope: PolicyScope | undefined,
+	scopeMatch: FilterScopeMatch | undefined,
+): string => {
+	const clientId = policyScope?.clientId;
+
+	if ("string" === typeof clientId) {
+		return FilterScopeMatch.Exact === scopeMatch
+			? `@clientId:{${clientId}}`
+			: `( @clientId:{${clientId}} | ismissing(@clientId) )`;
+	}
+
+	return FilterScopeMatch.Exact === scopeMatch ? "ismissing(@clientId)" : "";
+};
+
+/*
+ * Search command example:
+ *
+ * ft.search index:test "( @clientId:{value} | ismissing(@clientId) )
+ * (
+ * ( @ip:[value] | ( @ipRangeMin:[-inf value] @ipRangeMax:[value +inf] ) ) |
+ * @id:{value} | @ja4Fingerprint:{value} | headersFingerprint:{value}"
+ * )
+ * DIALECT 2 # must have when the ismissing() function in use
+ * */
+export const getRulesRedisQuery = (
+	filter: AccessRulesFilter,
+	matchingFieldsOnly: boolean,
+): string => {
+	const { policyScope, userScope } = filter;
+	const queryParts = [];
+
+	if (filter.groupId) {
+		queryParts.push(`@groupId:{${filter.groupId}}`);
+	}
+
+	const policyScopeQuery = getPolicyScopeQuery(
+		policyScope,
+		filter.policyScopeMatch,
+	);
+
+	if (policyScopeQuery) {
+		queryParts.push(policyScopeQuery);
+	}
+
+	if (userScope && Object.keys(userScope).length > 0) {
+		const userScopeFilter = getUserScopeQuery(
+			userScope,
+			filter.userScopeMatch,
+			matchingFieldsOnly,
+		);
+
+		queryParts.push(`( ${userScopeFilter} )`);
+	}
+
+	return queryParts.length > 0 ? queryParts.join(" ") : "*";
+};