@prosopo/user-access-policy 3.6.0 → 3.7.11

package/src/redis/redisRulesWriter.ts

@@ -0,0 +1,158 @@
+// 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 { chunkIntoBatches, executeBatchesSequentially } from "@prosopo/common";
+import type { Logger } from "@prosopo/logger";
+import type { RedisClientType } from "redis";
+import { REDIS_BATCH_SIZE } from "#policy/redis/redisClient.js";
+import type { AccessRule } from "#policy/rule.js";
+import type {
+	AccessRuleEntry,
+	AccessRulesWriter,
+} from "#policy/rulesStorage.js";
+import {
+	ACCESS_RULE_REDIS_KEY_PREFIX,
+	getAccessRuleRedisKey,
+} from "./redisRuleIndex.js";
+
+export class RedisRulesWriter implements AccessRulesWriter {
+	constructor(
+		private readonly client: RedisClientType,
+		private readonly logger: Logger,
+	) {}
+
+	async insertRules(ruleEntries: AccessRuleEntry[]): Promise<string[]> {
+		const entryBatches = chunkIntoBatches(ruleEntries, REDIS_BATCH_SIZE);
+
+		const keyBatches = await executeBatchesSequentially(
+			entryBatches,
+			async (entriesBatch) => this.insertRuleEntries(entriesBatch),
+		);
+
+		return keyBatches.flatMap((ruleKey) =>
+			ruleKey.slice(ACCESS_RULE_REDIS_KEY_PREFIX.length),
+		);
+	}
+
+	async deleteRules(ruleIds: string[]): Promise<void> {
+		const ruleKeys = ruleIds.map(
+			(ruleId) => ACCESS_RULE_REDIS_KEY_PREFIX + ruleId,
+		);
+
+		const keyBatches = chunkIntoBatches(ruleKeys, REDIS_BATCH_SIZE);
+
+		await executeBatchesSequentially(keyBatches, async (keysBatch) => {
+			const queries = this.client.multi();
+
+			for (const ruleKey of keysBatch) {
+				queries.del(ruleKey);
+			}
+
+			await queries.exec();
+		});
+	}
+
+	async deleteAllRules(): Promise<number> {
+		let cursor = "0";
+		let total = 0;
+
+		do {
+			const reply = await this.client.scan(cursor, {
+				MATCH: `${ACCESS_RULE_REDIS_KEY_PREFIX}*`,
+				COUNT: REDIS_BATCH_SIZE,
+			});
+
+			const ids = reply.keys.map((key) =>
+				key.slice(ACCESS_RULE_REDIS_KEY_PREFIX.length),
+			);
+			await this.deleteRules(ids);
+
+			total += ids.length;
+			cursor = reply.cursor;
+		} while ("0" !== cursor);
+
+		return total;
+	}
+
+	protected async insertRuleEntries(
+		ruleEntries: AccessRuleEntry[],
+	): Promise<string[]> {
+		const queries = this.client.multi();
+
+		const ruleKeys = ruleEntries.map((ruleEntry) => {
+			const { rule, expiresUnixTimestamp } = ruleEntry;
+
+			const ruleKey = getAccessRuleRedisKey(rule);
+			const ruleValue = getRedisRuleValue(rule);
+
+			queries.hSet(ruleKey, ruleValue);
+
+			if (expiresUnixTimestamp) {
+				// Redis expireAt expects seconds. Validate that timestamp is in seconds, not milliseconds.
+				// Unix timestamps in milliseconds (since 1970) are > 10 billion
+				// Unix timestamps in seconds won't reach 10 billion until year 2286
+				const MILLISECOND_THRESHOLD = 10_000_000_000;
+				if (expiresUnixTimestamp > MILLISECOND_THRESHOLD) {
+					throw new Error(
+						`Invalid expiry timestamp: ${expiresUnixTimestamp}. Timestamp must be in seconds, not milliseconds.`,
+					);
+				}
+				queries.expireAt(ruleKey, expiresUnixTimestamp);
+			}
+
+			return ruleKey;
+		});
+
+		await queries.exec();
+
+		return ruleKeys;
+	}
+}
+
+export const getRedisRuleValue = (rule: AccessRule): Record<string, string> =>
+	Object.fromEntries(
+		Object.entries(rule).map(([key, value]) => [key, String(value)]),
+	);
+
+export class DummyRedisRulesWriter implements AccessRulesWriter {
+	constructor(private readonly logger: Logger) {}
+
+	async insertRules(ruleEntries: AccessRuleEntry[]): Promise<string[]> {
+		this.logger.info(() => ({
+			msg: "Dummy insertRules() has no effect (redis is not ready)",
+			data: {
+				ruleEntries,
+			},
+		}));
+
+		return [];
+	}
+
+	async deleteRules(ruleIds: string[]): Promise<void> {
+		this.logger.info(() => ({
+			msg: "Dummy deleteRules() has no effect (redis is not ready)",
+			data: {
+				ruleIds,
+			},
+		}));
+	}
+
+	async deleteAllRules(): Promise<number> {
+		this.logger.info(() => ({
+			msg: "Dummy deleteAllRules() has no effect (redis is not ready)",
+		}));
+
+		return 0;
+	}
+}

package/src/rule.ts

@@ -0,0 +1,59 @@
+// 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 { CaptchaType } from "@prosopo/types";
+
+export enum AccessPolicyType {
+	Block = "block",
+	Restrict = "restrict",
+}
+
+export type AccessPolicy = {
+	type: AccessPolicyType;
+	captchaType?: CaptchaType;
+	description?: string;
+	solvedImagesCount?: number;
+	imageThreshold?: number;
+	powDifficulty?: number;
+	unsolvedImagesCount?: number;
+	frictionlessScore?: number;
+};
+
+export type PolicyScope = {
+	clientId?: string;
+};
+
+export type UserIp = {
+	numericIp?: bigint;
+	numericIpMaskMin?: bigint;
+	numericIpMaskMax?: bigint;
+};
+
+export type UserAttributes = {
+	userId?: string;
+	ja4Hash?: string;
+	headersHash?: string;
+	userAgentHash?: string;
+	headHash?: string;
+	coords?: string;
+	countryCode?: string;
+};
+
+export type UserScope = UserAttributes & UserIp;
+
+// flat structure is used to fit the Redis requirements
+export type AccessRule = AccessPolicy &
+	PolicyScope &
+	UserScope & {
+		groupId?: string;
+	};

package/src/ruleInput/.export.ts

@@ -0,0 +1,19 @@
+// 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 { accessRuleInput, type AccessRulesFilterInput } from "./ruleInput.js";
+
+export { accessPolicyInput, policyScopeInput } from "./policyInput.js";
+
+export { userScopeInput } from "./userScopeInput.js";

package/src/ruleInput/policyInput.ts

@@ -0,0 +1,51 @@
+// 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 } from "@prosopo/common";
+import { CaptchaTypeSchema } from "@prosopo/types";
+import { type ZodType, z } from "zod";
+import {
+	type AccessPolicy,
+	AccessPolicyType,
+	type PolicyScope,
+} from "#policy/rule.js";
+
+export const accessPolicyInput = z.object({
+	type: z.nativeEnum(AccessPolicyType),
+	captchaType: CaptchaTypeSchema.optional(),
+	description: z.coerce.string().optional(),
+	// Redis stores values as strings, so coerce is needed to parse properly
+	solvedImagesCount: z.coerce.number().optional(),
+	// the percentage of image panels that must be solved per image CAPTCHA
+	imageThreshold: z.coerce.number().optional(),
+	// the Proof-of-Work difficulty level
+	powDifficulty: z.coerce.number().optional(),
+	// the number of unsolved image CAPTCHA challenges to serve
+	unsolvedImagesCount: z.coerce.number().optional(),
+	// used to increase the user's score
+	frictionlessScore: z.coerce.number().optional(),
+} satisfies AllKeys<AccessPolicy>) satisfies ZodType<AccessPolicy>;
+
+// Sanitize block policies by removing captchaType and solvedImagesCount
+export const sanitizeAccessPolicy = (policy: AccessPolicy): AccessPolicy => {
+	if (policy.type === AccessPolicyType.Block) {
+		const { captchaType, solvedImagesCount, ...blockPolicy } = policy;
+		return blockPolicy;
+	}
+	return policy;
+};
+
+export const policyScopeInput = z.object({
+	clientId: z.coerce.string().optional(),
+} satisfies AllKeys<PolicyScope>) satisfies ZodType<PolicyScope>;

package/src/ruleInput/ruleInput.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 { AllKeys } from "@prosopo/common";
+import { type ZodType, z } from "zod";
+import type { AccessPolicy, AccessRule, PolicyScope } from "#policy/rule.js";
+import {
+	type AccessRuleEntry,
+	type AccessRulesFilter,
+	FilterScopeMatch,
+} from "#policy/rulesStorage.js";
+import { accessPolicyInput, policyScopeInput } from "./policyInput.js";
+import { type UserScopeInput, userScopeInput } from "./userScopeInput.js";
+
+type RuleGroupInput = {
+	groupId?: string;
+	ruleGroupId?: string;
+};
+
+export type AccessRuleInput = AccessPolicy &
+	PolicyScope &
+	UserScopeInput &
+	RuleGroupInput;
+
+const ruleGroupInput = z
+	.object({
+		groupId: z.coerce.string().optional(),
+		ruleGroupId: z.coerce.string().optional(),
+	} satisfies AllKeys<RuleGroupInput>)
+	.transform((ruleGroupInput: RuleGroupInput) => {
+		const { ruleGroupId, ...ruleGroup } = ruleGroupInput;
+
+		if ("string" === typeof ruleGroupId) {
+			ruleGroup.groupId = ruleGroupId;
+		}
+
+		return ruleGroup;
+	});
+
+export const accessRuleInput: ZodType<AccessRule> = z
+	.object({
+		...accessPolicyInput.shape,
+		...policyScopeInput.shape,
+	})
+	.and(userScopeInput)
+	.and(ruleGroupInput)
+	// transform is used for type safety only - plain "satisfies ZodType<x>" doesn't work after ".and()"
+	.transform((ruleInput: AccessRuleInput): AccessRule => ruleInput);
+
+export const ruleEntryInput = z.object({
+	rule: accessRuleInput,
+	expiresUnixTimestamp: z.coerce.number().optional(),
+} satisfies AllKeys<AccessRuleEntry>) satisfies ZodType<AccessRuleEntry>;
+
+export type AccessRulesFilterInput = AccessRulesFilter & {
+	userScope?: UserScopeInput;
+	policyScopes?: PolicyScope[];
+};
+
+export const accessRulesFilterInput = z.object({
+	policyScope: policyScopeInput.optional(),
+	policyScopes: z.array(policyScopeInput).optional(),
+	policyScopeMatch: z
+		.nativeEnum(FilterScopeMatch)
+		.default(FilterScopeMatch.Exact),
+	userScope: userScopeInput.optional(),
+	userScopeMatch: z
+		.nativeEnum(FilterScopeMatch)
+		.default(FilterScopeMatch.Exact),
+	groupId: z.string().optional(),
+} satisfies AllKeys<AccessRulesFilterInput>) satisfies ZodType<AccessRulesFilterInput>;
+
+export const getAccessRuleFiltersFromInput = (
+	filterInput: AccessRulesFilterInput,
+): AccessRulesFilter[] => {
+	const { policyScopes, policyScope, ...filterBase } = filterInput;
+
+	const allPolicyScopes = policyScopes || [];
+
+	if (policyScope) {
+		allPolicyScopes.push(policyScope);
+	}
+
+	if (allPolicyScopes.length > 0) {
+		return allPolicyScopes.map((policyScope) => ({
+			...filterBase,
+			policyScope,
+		}));
+	}
+
+	return [filterBase];
+};

package/src/ruleInput/userScopeInput.ts

@@ -0,0 +1,108 @@
+// 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 crypto from "node:crypto";
+import type { AllKeys } from "@prosopo/common";
+import { getIPAddress } from "@prosopo/util";
+import { Address4 } from "ip-address";
+import { type ZodType, z } from "zod";
+import type { UserAttributes, UserIp, UserScope } from "#policy/rule.js";
+import type { UserAttributesRecord, UserIpRecord } from "#policy/ruleRecord.js";
+
+export type UserAttributesInput = UserAttributes & UserAttributesRecord;
+
+const userAttributesSchema = z.object({
+	// coerce is used for safety, as e.g., incoming userId can be digital
+	userId: z.coerce.string().optional(),
+	ja4Hash: z.coerce.string().optional(),
+	headersHash: z.coerce.string().optional(),
+	userAgentHash: z.coerce.string().optional(),
+	headHash: z.coerce.string().optional(),
+	coords: z.coerce.string().optional(),
+	countryCode: z.coerce.string().optional(),
+} satisfies AllKeys<UserAttributes>) satisfies ZodType<UserAttributes>;
+
+const userAttributesInput = z
+	.object({
+		...userAttributesSchema.shape,
+		userAgent: z.coerce.string().optional(),
+	} satisfies AllKeys<UserAttributesInput>)
+	.transform((userAttributesInput: UserAttributesInput): UserAttributes => {
+		// this line creates a new "userAttributes", without userAgent
+		const { userAgent, ...userScope } = userAttributesInput;
+
+		if ("string" === typeof userAgent) {
+			userScope.userAgentHash = hashUserAgent(userAgent);
+		}
+
+		return userScope;
+	});
+
+const hashUserAgent = (userAgent: string): string =>
+	crypto.createHash("sha256").update(userAgent).digest("hex");
+
+export type UserIpInput = UserIp & UserIpRecord;
+
+const userIpSchema = z.object({
+	numericIp: z.coerce.bigint().optional(),
+	numericIpMaskMin: z.coerce.bigint().optional(),
+	numericIpMaskMax: z.coerce.bigint().optional(),
+} satisfies AllKeys<UserIp>) satisfies ZodType<UserIp>;
+
+const userIpInput = z
+	.object({
+		...userIpSchema.shape,
+		ip: z.string().optional(),
+		ipMask: z.string().optional(),
+	} satisfies AllKeys<UserIpInput>)
+	.transform((userIpInput: UserIpInput): UserIp => {
+		// this line creates a new "userScope", without ip and ipMask
+		const { ip, ipMask, ...numericUserIp } = userIpInput;
+
+		if ("string" === typeof ip) {
+			numericUserIp.numericIp = getIPAddress(ip).bigInt();
+		}
+
+		// Assuming ipMask is already validated to be a string in CIDR format
+		if ("string" === typeof ipMask) {
+			// Create an Address4 object from the CIDR string.
+			// Address4 automatically understands CIDR notation and represents the entire network range.
+			const ipObject = new Address4(ipMask);
+
+			// The minimum IP in the CIDR range is the start address of the network.
+			numericUserIp.numericIpMaskMin = ipObject.startAddress().bigInt();
+
+			// The maximum IP in the CIDR range is the end address of the network.
+			numericUserIp.numericIpMaskMax = ipObject.endAddress().bigInt();
+		}
+
+		return numericUserIp;
+	});
+
+export type UserScopeInput = UserAttributesInput & UserIpInput;
+
+export const userScopeSchema = z.object({
+	...userIpSchema.shape,
+	...userAttributesSchema.shape,
+} satisfies AllKeys<UserScope>) satisfies ZodType<UserScope>;
+
+export const userScopeInput = z
+	.object({})
+	// unlike ...shape(), .and() includes transformations
+	.and(userIpInput)
+	.and(userAttributesInput)
+	.transform(
+		// transform is used for type safety only - plain "satisfies ZodType<x>" doesn't work after ".and()"
+		(userScopeInput): UserScopeInput => userScopeInput,
+	);

package/src/ruleRecord.ts

@@ -0,0 +1,69 @@
+// 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 {
+	AccessPolicy,
+	PolicyScope,
+	UserAttributes,
+} from "#policy/rule.js";
+
+export type UserAttributesRecord = Omit<UserAttributes, "userAgentHash"> & {
+	userAgent?: string;
+};
+
+export const userAttributesRecordFields = [
+	"userId",
+	"ja4Hash",
+	"headersHash",
+	"userAgent",
+	"headHash",
+	"coords",
+	"countryCode",
+] as const satisfies (keyof UserAttributesRecord)[];
+
+export type UserIpRecord = {
+	// human-friendly ip versions.
+	ip?: string;
+	// 127.0.0.1/24
+	ipMask?: string;
+};
+
+export const userIpRecordFields = [
+	"ip",
+	"ipMask",
+] as const satisfies (keyof UserIpRecord)[];
+
+export type UserScopeRecord = UserAttributesRecord & UserIpRecord;
+
+export const userScopeRecordFields = [
+	...userAttributesRecordFields,
+	...userIpRecordFields,
+] as const satisfies (keyof UserScopeRecord)[];
+
+export type UserScopeRecordField = (typeof userScopeRecordFields)[number];
+
+export type AccessRuleRecord = AccessPolicy &
+	PolicyScope &
+	UserScopeRecord & {
+		ruleGroupId?: string;
+	};
+
+export const getUserScopeRecordFromAccessRuleRecord = (
+	ruleRecord: AccessRuleRecord,
+): UserScopeRecord =>
+	Object.fromEntries(
+		userScopeRecordFields
+			.map((field) => [field, ruleRecord[field]])
+			.filter(([, value]) => value !== undefined),
+	);

package/src/rulesStorage.ts

@@ -0,0 +1,72 @@
+// 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 { AccessRule, PolicyScope, UserScope } from "#policy/rule.js";
+
+export enum FilterScopeMatch {
+	Exact = "exact",
+	Greedy = "greedy",
+}
+
+export type AccessRulesFilter = {
+	policyScope?: PolicyScope;
+	/**
+	 * Exact: "clientId" => client rules, "undefined" => global rules. Used by the API
+	 * Greedy: "clientId" => client + global rules, "undefined" => any rules. Used by the Express middleware
+	 */
+	policyScopeMatch?: FilterScopeMatch;
+	userScope?: UserScope;
+	/**
+	 * Exact: "clientId" => client rules, "undefined" => global rules. Used by the API
+	 * Greedy: "clientId" => client + global rules, "undefined" => any rules. Used by the Express middleware
+	 */
+	userScopeMatch?: FilterScopeMatch;
+	groupId?: string;
+};
+
+export type AccessRuleEntry = {
+	rule: AccessRule;
+	expiresUnixTimestamp?: number;
+};
+
+export type AccessRulesReader = {
+	fetchRules(ruleIds: string[]): Promise<AccessRuleEntry[]>;
+
+	getMissingRuleIds(ruleIds: string[]): Promise<string[]>;
+
+	findRules(
+		filter: AccessRulesFilter,
+		matchingFieldsOnly?: boolean,
+		skipEmptyUserScopes?: boolean,
+	): Promise<AccessRule[]>;
+
+	findRuleIds(
+		filter: AccessRulesFilter,
+		matchingFieldsOnly?: boolean,
+	): Promise<string[]>;
+
+	fetchAllRuleIds(
+		batchHandler: (ruleIds: string[]) => Promise<void>,
+	): Promise<void>;
+};
+
+export type AccessRulesWriter = {
+	insertRules(ruleEntries: AccessRuleEntry[]): Promise<string[]>;
+
+	deleteRules(ruleIds: string[]): Promise<void>;
+
+	deleteAllRules(): Promise<number>;
+};
+
+export type AccessRulesStorage = AccessRulesReader & AccessRulesWriter;