@prosopo/user-access-policy 3.6.0 → 3.7.12

package/src/api/read/findRuleIds.ts

@@ -0,0 +1,95 @@
+// 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 AllKeys, executeBatchesSequentially } from "@prosopo/common";
+import type { Logger } from "@prosopo/logger";
+import { type ZodType, z } from "zod";
+import {
+	type AccessRulesFilterInput,
+	accessRulesFilterInput,
+	getAccessRuleFiltersFromInput,
+} from "#policy/ruleInput/ruleInput.js";
+import type { AccessRulesStorage } from "#policy/rulesStorage.js";
+
+type FindRulesSchema = ZodType<AccessRulesFilterInput[]>;
+
+export type RuleIdsResponse = {
+	ruleIds: string[];
+};
+
+export const ruleIdsResponse = z.object({
+	ruleIds: z.string().array(),
+} satisfies AllKeys<RuleIdsResponse>) satisfies ZodType<RuleIdsResponse>;
+
+export type RuleIdsEndpointResponse = ApiEndpointResponse & {
+	data?: RuleIdsResponse;
+};
+
+export class FindRuleIdsEndpoint implements ApiEndpoint<FindRulesSchema> {
+	public constructor(
+		private readonly accessRulesStorage: AccessRulesStorage,
+		private readonly logger: Logger,
+	) {}
+
+	public getRequestArgsSchema(): FindRulesSchema {
+		return z.array(accessRulesFilterInput);
+	}
+
+	async processRequest(
+		args: AccessRulesFilterInput[],
+		logger?: Logger,
+	): Promise<RuleIdsEndpointResponse> {
+		const log = logger ?? this.logger;
+		const ruleIdBatches = await executeBatchesSequentially(
+			args,
+			async (rulesFilterInput) => {
+				const ruleFilters = getAccessRuleFiltersFromInput(rulesFilterInput);
+
+				const ruleIds = await executeBatchesSequentially(
+					ruleFilters,
+					(ruleFilter) => this.accessRulesStorage.findRuleIds(ruleFilter),
+				);
+
+				return ruleIds.flat();
+			},
+		);
+
+		const ruleIds = ruleIdBatches.flat();
+
+		// Set() automatically removes duplicates
+		const uniqueRuleIds = [...new Set(ruleIds)];
+
+		log.info(() => ({
+			msg: "Endpoint found rules",
+			data: {
+				totalFoundCount: ruleIds.length,
+				uniqueFoundCount: uniqueRuleIds.length,
+				searchFilters: args,
+				foundIds: uniqueRuleIds,
+			},
+		}));
+
+		return {
+			status: ApiEndpointResponseStatus.SUCCESS,
+			data: {
+				ruleIds: uniqueRuleIds,
+			},
+		};
+	}
+}

package/src/api/read/getMissingIds.ts

@@ -0,0 +1,81 @@
+// 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 { AllKeys } from "@prosopo/common";
+import type { Logger } from "@prosopo/logger";
+import { type ZodType, z } from "zod";
+import type { AccessRulesStorage } from "#policy/rulesStorage.js";
+
+export type MissingIds = string[];
+
+type MissingIdsSchema = ZodType<MissingIds>;
+
+export type MissingIdsResponse = {
+	ids: string[];
+};
+
+export const missingIdsResponse = z.object({
+	ids: z.string().array(),
+} satisfies AllKeys<MissingIdsResponse>) satisfies ZodType<MissingIdsResponse>;
+
+export type MissingIdsEndpointResponse = ApiEndpointResponse & {
+	data?: MissingIdsResponse;
+};
+
+export class GetMissingIdsEndpoint implements ApiEndpoint<MissingIdsSchema> {
+	public constructor(
+		private readonly accessRulesStorage: AccessRulesStorage,
+		private readonly logger: Logger,
+	) {}
+
+	public getRequestArgsSchema(): MissingIdsSchema {
+		return z.string().array();
+	}
+
+	async processRequest(
+		args: MissingIds,
+		logger?: Logger,
+	): Promise<MissingIdsEndpointResponse> {
+		const log = logger ?? this.logger;
+		const missingIds = await this.accessRulesStorage.getMissingRuleIds(args);
+
+		log.info(() => ({
+			msg: "Endpoint checked missing ids",
+			data: {
+				idsToCheck: args.length,
+				missingIds: missingIds.length,
+			},
+		}));
+
+		log.debug(() => ({
+			msg: "Missing id details",
+			data: {
+				idsToCheck: args,
+				missingIds: missingIds,
+			},
+		}));
+
+		return {
+			status: ApiEndpointResponseStatus.SUCCESS,
+			data: {
+				ids: missingIds,
+			},
+		};
+	}
+}

package/src/api/ruleApiRoutes.ts

@@ -0,0 +1,146 @@
+// 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 {
+	ApiRouteLimits,
+	ApiRoutes,
+	ApiRoutesProvider,
+} from "@prosopo/api-route";
+import type { AllEnumValues } from "@prosopo/common";
+import type { Logger } from "@prosopo/logger";
+import { FetchRulesEndpoint } from "#policy/api/read/fetchRules.js";
+import { FindRuleIdsEndpoint } from "#policy/api/read/findRuleIds.js";
+import { GetMissingIdsEndpoint } from "#policy/api/read/getMissingIds.js";
+import { RehashRulesEndpoint } from "#policy/api/write/rehashRules.js";
+import type { AccessRulesStorage } from "#policy/rulesStorage.js";
+import { DeleteAllRulesEndpoint } from "./delete/deleteAllRules.js";
+import { DeleteRuleGroupsEndpoint } from "./delete/deleteRuleGroups.js";
+import { DeleteRulesEndpoint } from "./delete/deleteRules.js";
+import { InsertRulesEndpoint } from "./write/insertRules.js";
+
+export enum accessRuleApiPaths {
+	// delete
+	DELETE_ALL = "/v1/prosopo/user-access-policy/rules/delete-all",
+	DELETE_GROUPS = "/v1/prosopo/user-access-policy/rules/delete-groups",
+	DELETE_MANY = "/v1/prosopo/user-access-policy/rules/delete-many",
+	// read
+	FETCH_MANY = "/v1/prosopo/user-access-policy/rules/fetch-many",
+	FIND_IDS = "/v1/prosopo/user-access-policy/rules/find-ids",
+	GET_MISSING_IDS = "/v1/prosopo/user-access-policy/rules/get-missing-ids",
+	// write
+	INSERT_MANY = "/v1/prosopo/user-access-policy/rules/insert-many",
+	REHASH_ALL = "/v1/prosopo/user-access-policy/rules/rehash-all",
+}
+
+export class AccessRuleApiRoutes implements ApiRoutesProvider {
+	public constructor(
+		private readonly accessRulesStorage: AccessRulesStorage,
+		private readonly logger: Logger,
+	) {}
+
+	public getRoutes(): ApiRoutes {
+		return {
+			...this.makeDeleteEndpoints(),
+			...this.makeReadEndpoints(),
+			...this.makeWriteEndpoints(),
+		} satisfies AllEnumValues<accessRuleApiPaths>;
+	}
+
+	protected makeDeleteEndpoints() {
+		return {
+			[accessRuleApiPaths.DELETE_ALL]: new DeleteAllRulesEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+			[accessRuleApiPaths.DELETE_GROUPS]: new DeleteRuleGroupsEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+			[accessRuleApiPaths.DELETE_MANY]: new DeleteRulesEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+		};
+	}
+
+	protected makeReadEndpoints() {
+		return {
+			[accessRuleApiPaths.FETCH_MANY]: new FetchRulesEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+			[accessRuleApiPaths.FIND_IDS]: new FindRuleIdsEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+			[accessRuleApiPaths.GET_MISSING_IDS]: new GetMissingIdsEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+		};
+	}
+
+	protected makeWriteEndpoints() {
+		return {
+			[accessRuleApiPaths.INSERT_MANY]: new InsertRulesEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+			[accessRuleApiPaths.REHASH_ALL]: new RehashRulesEndpoint(
+				this.accessRulesStorage,
+				this.logger,
+			),
+		};
+	}
+}
+
+export const getExpressApiRuleRateLimits =
+	(): ApiRouteLimits<accessRuleApiPaths> => {
+		const defaults = {
+			limit: 5,
+			windowSeconds: 10,
+		};
+
+		const defaultWindowMs = defaults.windowSeconds * 1_000;
+
+		const rateLimitEntries = Object.entries(accessRuleApiPaths).map(
+			([endpointName, endpointPath]) => [
+				endpointPath,
+				{
+					windowMs:
+						getIntEnvironmentVariable(
+							`PROSOPO_USER_ACCESS_POLICY_RULE_${endpointName}_WINDOW`,
+						) || defaultWindowMs,
+					limit:
+						getIntEnvironmentVariable(
+							`PROSOPO_USER_ACCESS_POLICY_RULE_${endpointName}_LIMIT`,
+						) || defaults.limit,
+				},
+			],
+		);
+
+		return Object.fromEntries(rateLimitEntries);
+	};
+
+const getIntEnvironmentVariable = (
+	variableName: string,
+): number | undefined => {
+	const variableValue = process.env[variableName];
+
+	const numericValue = variableValue
+		? Number.parseInt(variableValue)
+		: Number.NaN;
+
+	return Number.isInteger(numericValue) ? numericValue : undefined;
+};

package/src/api/rulesApiClient.ts

@@ -0,0 +1,154 @@
+// 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 { ApiClient } from "@prosopo/api";
+import type { ApiEndpointResponse } from "@prosopo/api-route";
+import {
+	type FetchRulesEndpointResponse,
+	type FetchRulesOptions,
+	fetchRulesResponse,
+} from "#policy/api/read/fetchRules.js";
+import {
+	type RuleIdsEndpointResponse,
+	ruleIdsResponse,
+} from "#policy/api/read/findRuleIds.js";
+import {
+	type MissingIds,
+	type MissingIdsEndpointResponse,
+	missingIdsResponse,
+} from "#policy/api/read/getMissingIds.js";
+import type { AccessRulesFilterInput } from "#policy/ruleInput/ruleInput.js";
+import type { DeleteSiteGroups } from "./delete/deleteRuleGroups.js";
+import { accessRuleApiPaths } from "./ruleApiRoutes.js";
+import type { InsertRulesGroup } from "./write/insertRules.js";
+
+export class AccessRulesApiClient extends ApiClient {
+	//// delete
+
+	public deleteMany(
+		filters: AccessRulesFilterInput[],
+		jwt: string,
+	): Promise<ApiEndpointResponse> {
+		return this.post(
+			accessRuleApiPaths.DELETE_MANY,
+			filters,
+			this.getAuthHeaders(jwt),
+		);
+	}
+
+	public deleteGroups(
+		siteGroups: DeleteSiteGroups,
+		jwt: string,
+	): Promise<ApiEndpointResponse> {
+		return this.post(
+			accessRuleApiPaths.DELETE_GROUPS,
+			siteGroups,
+			this.getAuthHeaders(jwt),
+		);
+	}
+
+	public deleteAll(jwt: string): Promise<ApiEndpointResponse> {
+		return this.post(
+			accessRuleApiPaths.DELETE_ALL,
+			{},
+			this.getAuthHeaders(jwt),
+		);
+	}
+
+	//// read
+
+	public async getMissingIds(
+		idsToCheck: MissingIds,
+		jwt: string,
+	): Promise<MissingIdsEndpointResponse> {
+		const endpointResponse: ApiEndpointResponse = await this.post(
+			accessRuleApiPaths.GET_MISSING_IDS,
+			idsToCheck,
+			this.getAuthHeaders(jwt),
+		);
+
+		const parsedData = missingIdsResponse.safeParse(endpointResponse.data);
+
+		return {
+			...endpointResponse,
+			data: parsedData.success ? parsedData.data : undefined,
+		};
+	}
+
+	public async fetchMany(
+		fetchOptions: FetchRulesOptions,
+		jwt: string,
+	): Promise<FetchRulesEndpointResponse> {
+		const endpointResponse: ApiEndpointResponse = await this.post(
+			accessRuleApiPaths.FETCH_MANY,
+			fetchOptions,
+			this.getAuthHeaders(jwt),
+		);
+
+		const parsedData = fetchRulesResponse.safeParse(endpointResponse.data);
+
+		return {
+			...endpointResponse,
+			data: parsedData.success ? parsedData.data : undefined,
+		};
+	}
+
+	public async findIds(
+		filters: AccessRulesFilterInput[],
+		jwt: string,
+	): Promise<RuleIdsEndpointResponse> {
+		const endpointResponse: ApiEndpointResponse = await this.post(
+			accessRuleApiPaths.FIND_IDS,
+			filters,
+			this.getAuthHeaders(jwt),
+		);
+
+		const parsedData = ruleIdsResponse.safeParse(endpointResponse.data);
+
+		return {
+			...endpointResponse,
+			data: parsedData.success ? parsedData.data : undefined,
+		};
+	}
+
+	//// write
+
+	public async rehashAll(jwt: string): Promise<ApiEndpointResponse> {
+		return this.post(
+			accessRuleApiPaths.REHASH_ALL,
+			{},
+			this.getAuthHeaders(jwt),
+		);
+	}
+
+	public insertMany(
+		ruleGroups: InsertRulesGroup[],
+		jwt: string,
+	): Promise<ApiEndpointResponse> {
+		return this.post(
+			accessRuleApiPaths.INSERT_MANY,
+			ruleGroups,
+			this.getAuthHeaders(jwt),
+		);
+	}
+
+	protected getAuthHeaders(jwt: string): RequestInit {
+		return {
+			headers: {
+				"Prosopo-Site-Key": this.account,
+				Authorization: `Bearer ${jwt}`,
+			},
+		};
+	}
+}

package/src/api/write/.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 type { InsertRulesGroup } from "./insertRules.js";

package/src/api/write/insertRules.ts

@@ -0,0 +1,183 @@
+// 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 { AllKeys } from "@prosopo/common";
+import { LogLevel, type Logger } from "@prosopo/logger";
+import { type ZodType, z } from "zod";
+import type {
+	AccessPolicy,
+	AccessRule,
+	PolicyScope,
+	UserScope,
+} from "#policy/rule.js";
+import {
+	accessPolicyInput,
+	policyScopeInput,
+	sanitizeAccessPolicy,
+} from "#policy/ruleInput/policyInput.js";
+import {
+	type UserScopeInput,
+	userScopeInput,
+} from "#policy/ruleInput/userScopeInput.js";
+import type {
+	AccessRuleEntry,
+	AccessRulesWriter,
+} from "#policy/rulesStorage.js";
+
+export type InsertRulesGroup = {
+	accessPolicy: AccessPolicy;
+	userScopes: UserScopeInput[];
+	// a single client may have multiple siteKeys,
+	// so for batch requests we take multiple policyScopes as apply all the rules to every scope
+	policyScopes?: PolicyScope[];
+	groupId?: string;
+	expiresUnixTimestamp?: number;
+};
+
+type ParsedInsertRulesGroup = InsertRulesGroup & {
+	userScopes: UserScope[];
+};
+
+type ParsedInsertRuleGroups = ParsedInsertRulesGroup[];
+
+type InsertRulesSchema = ZodType<InsertRulesGroup[]>;
+
+export class InsertRulesEndpoint implements ApiEndpoint<InsertRulesSchema> {
+	public constructor(
+		private readonly accessRulesWriter: AccessRulesWriter,
+		private readonly logger: Logger,
+	) {}
+
+	public getRequestArgsSchema(): InsertRulesSchema {
+		return z.array(
+			z.object({
+				accessPolicy: accessPolicyInput,
+				policyScopes: z.array(policyScopeInput).optional(),
+				groupId: z.string().optional(),
+				userScopes: z.array(userScopeInput),
+				expiresUnixTimestamp: z.number().optional(),
+			} satisfies AllKeys<InsertRulesGroup>),
+		);
+	}
+
+	async processRequest(
+		args: ParsedInsertRuleGroups,
+		logger?: Logger,
+	): Promise<ApiEndpointResponse> {
+		const log = logger ?? this.logger;
+
+		const timeoutPromise = new Promise<ApiEndpointResponse>((resolve) => {
+			setTimeout(() => {
+				resolve({
+					status: ApiEndpointResponseStatus.PROCESSING,
+				});
+			}, 5000);
+		});
+
+		const userScopesCount = args.reduce(
+			(userScopesCount, group) => userScopesCount + group.userScopes.length,
+			0,
+		);
+
+		const createRulesPromise = this.createRuleGroups(args)
+			.then((insertedIds) => {
+				log.info(() => ({
+					msg: "Endpoint inserted access rules",
+					data: {
+						userScopesCount: userScopesCount,
+						insertedCount: insertedIds.length,
+						uniqueIdsCount: new Set(insertedIds).size,
+					},
+				}));
+
+				log.debug(() => ({
+					msg: "Inserted access rules details",
+					data: {
+						insertedIds,
+						input: args,
+					},
+				}));
+
+				return {
+					status: ApiEndpointResponseStatus.SUCCESS,
+				};
+			})
+			.catch((error) => {
+				if (LogLevel.enum.debug === log.getLogLevel()) {
+					log.error(() => ({
+						err: error,
+						data: { args },
+						msg: "Failed to insert access rules",
+					}));
+				}
+				return {
+					status: ApiEndpointResponseStatus.FAIL,
+				};
+			});
+
+		// Whichever finishes first: timeout or actual rule creation
+		return Promise.race([timeoutPromise, createRulesPromise]);
+	}
+
+	protected async createRuleGroups(
+		groups: ParsedInsertRuleGroups,
+	): Promise<string[]> {
+		const ruleIdPromises = groups.map((group) => this.createRulesGroup(group));
+
+		const ruleIdSets = await Promise.all(ruleIdPromises);
+
+		return ruleIdSets.flat();
+	}
+
+	protected async createRulesGroup(
+		group: ParsedInsertRulesGroup,
+	): Promise<string[]> {
+		const ruleEntries: AccessRuleEntry[] = [];
+		const policyScopes = group.policyScopes || [];
+		// Sanitize the access policy to remove unnecessary fields from block policies
+		const sanitizedPolicy = sanitizeAccessPolicy(group.accessPolicy);
+
+		for (const userScope of group.userScopes) {
+			const ruleBase: AccessRule = {
+				...sanitizedPolicy,
+				...userScope,
+				...(group.groupId ? { groupId: group.groupId } : {}),
+			};
+
+			if (policyScopes.length > 0) {
+				for (const policyScope of policyScopes) {
+					ruleEntries.push({
+						rule: {
+							...ruleBase,
+							...policyScope,
+						},
+						expiresUnixTimestamp: group.expiresUnixTimestamp,
+					});
+				}
+			} else {
+				ruleEntries.push({
+					rule: ruleBase,
+					expiresUnixTimestamp: group.expiresUnixTimestamp,
+				});
+			}
+		}
+
+		return this.accessRulesWriter.insertRules(ruleEntries);
+	}
+}