@prosopo/user-access-policy 3.14.14 → 3.14.16

package/src/redis/redisRulesWriter.ts

@@ -1,172 +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 { 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, GLOBAL_CLIENT_SCOPE_SENTINEL } 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> => {
-	const record: Record<string, string> = {};
-	for (const [key, value] of Object.entries(rule)) {
-		if (value === undefined) {
-			continue;
-		}
-		record[key] = String(value);
-	}
-	// Global rules used to be stored with no clientId field at all and looked
-	// up via `ismissing(@clientId)`. Stamp the sentinel so the read path can
-	// probe `@clientId:{global}` instead — a posting-list intersection is
-	// orders of magnitude cheaper than ismissing over a large rule set.
-	// Rules with a real clientId are untouched.
-	if (record.clientId === undefined) {
-		record.clientId = GLOBAL_CLIENT_SCOPE_SENTINEL;
-	}
-	return record;
-};
-
-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

@@ -1,122 +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 { CaptchaType, ResultReason } from "@prosopo/types";
-
-export enum AccessPolicyType {
-	Block = "block",
-	Restrict = "restrict",
-	// Explicit allow-list: request that matches an Allow rule bypasses the
-	// challenge flow and gets an `authenticated` session (captchaType =
-	// authenticated on the frictionless response). Fires for any qualifying
-	// scope — verified Web Bot Auth agent, allow-listed IP, ja4/ja4_and_ip
-	// match, UA substring, ASN, country. IP-binding on the resulting
-	// session token defends against replay from a different IP. Opt-in per
-	// rule; the operator authors an Allow rule the same way they'd author
-	// a Block or Restrict rule.
-	Allow = "allow",
-}
-
-// Sentinel stamped on the Redis `clientId` field for rules that would
-// otherwise store undefined (i.e. global rules). Lets the read path
-// probe `@clientId:{global}` via the posting-list index instead of the
-// expensive `ismissing(@clientId)` set-difference walk that degrades
-// sharply once the global rule set grows into the 10k+ range. The
-// reader converts it back to `undefined` at parse time so downstream
-// code sees the original AccessRule shape. Kept in this types-only
-// module so both the writer/index side and the parser/input side can
-// import it without pulling in a circular dependency through
-// transformRule.
-export const GLOBAL_CLIENT_SCOPE_SENTINEL = "global";
-
-export type AccessPolicy = {
-	type: AccessPolicyType;
-	captchaType?: CaptchaType;
-	description?: string;
-	solvedImagesCount?: number;
-	imageThreshold?: number;
-	powDifficulty?: number;
-	unsolvedImagesCount?: number;
-	frictionlessScore?: number;
-	// When true, a Block policy does NOT fire at the request-time
-	// blockMiddleware (so the user does not see a 401 on the captcha
-	// challenge endpoint) — it fires at the verify step instead, marking
-	// the commitment ACCESS_POLICY_BLOCK / disapproved. The verify
-	// response returns `{verified:false}` to the dApp's server while the
-	// user-facing widget completes normally. Mirrors the existing
-	// coords-rule deferral pattern: the middleware blanks coords out of
-	// the userScope, so coords rules can only ever be matched in the
-	// verify path; `deferToVerify` is the explicit form for non-coords
-	// signals (ja4, headersHash, etc.) when the operator wants the
-	// attacker to pay the captcha-solving cost before being rejected.
-	deferToVerify?: boolean;
-	// Replaces "Forbidden" in the 403 body of a matched Block policy.
-	messageKey?: ResultReason;
-};
-
-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;
-	asn?: number;
-	// Operating system classified server-side from the request User-Agent (see
-	// `classifyOs`). Stored as a plain lowercase tag — one of `OsName` — and
-	// matched like `countryCode` (exact equality, not hashed). Lets a rule
-	// drop/limit requests from a given OS even when the client omits client
-	// hints.
-	os?: string;
-	browser?: string;
-	// Arbitrary-header matching (see `headerMatch.ts` and the portal Header
-	// Restriction card). A header rule carries `headerName` + `headerValue` +
-	// `headerOperator`; unlike the other dimensions these are checked in code
-	// against the raw request headers — Redis TAG can't express substring
-	// `contains` or per-rule operators — so they are not part of the Redis
-	// matching query. `headerMatch` is the indexed sentinel (always
-	// `HEADER_RULE_MARKER`) that makes such a rule a matching candidate for
-	// every request, so an allow-list rule still fires on a request that omits
-	// the target header.
-	headerMatch?: string;
-	headerName?: string;
-	headerValue?: string;
-	headerOperator?: string;
-	// Canonical Web Bot Auth Signature-Agent URL — e.g.
-	// "https://signatures.openai.com/". Matched at runtime against the
-	// `Signature-Agent` header after RFC 9421 Ed25519 verification succeeds.
-	// Stored as-is like `countryCode` (exact equality after normalisation).
-	// Rules with this field only match requests carrying a valid Web Bot
-	// Auth signature; unverified traffic falls through.
-	webBotAuthAgent?: 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

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

package/src/ruleInput/policyInput.ts

@@ -1,120 +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 } from "@prosopo/common";
-import { CaptchaTypeSchema, ResultReason } from "@prosopo/types";
-import { z } from "zod";
-import {
-	type AccessPolicy,
-	AccessPolicyType,
-	GLOBAL_CLIENT_SCOPE_SENTINEL,
-	type PolicyScope,
-} from "#policy/rule.js";
-
-// `satisfies ZodType<AccessPolicy>` is intentionally omitted: the
-// `deferToVerify` preprocess widens the schema's input type to `unknown`
-// (preprocess accepts anything), which fails the
-// `ZodType<T, ZodTypeDef, T>` identity check. The `AllKeys<AccessPolicy>`
-// constraint still catches missing-field regressions.
-//
-// The `superRefine` rejects Block+captchaType and Block+solvedImagesCount
-// at write time. Those fields are meaningless on a Block policy — the
-// sanitizer used to silently strip them, which meant operators writing
-// e.g. "block image captchas for this IP" got a rule that actually
-// blocked EVERY captcha type. The bug in #2885 (Block+deferToVerify 400
-// on every /captcha/*) was a knock-on of the same silent-strip: the
-// captchaType-equality check on the read side compared `undefined` to the
-// request's captchaType and rejected. Rejecting at input surfaces the
-// mismatch loudly so operators can adjust their intent (they usually
-// wanted a Restrict) rather than persisting a rule that doesn't match
-// what they typed.
-// Base ZodObject shape — reused via `.shape` by `ruleInput` and
-// `transformRule` (both compose accessPolicyInput's fields with policy /
-// user scope fields via object spread). Split from `accessPolicyInput`
-// below because that one applies a `.superRefine` and returns a
-// `ZodEffects`, which loses `.shape`.
-export const accessPolicyInputShape = 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(),
-	// Skip the request-time block middleware and only fire at verify.
-	// Redis stores booleans as strings — preprocess so "true"/"false"
-	// round-trip to the JS boolean the matcher expects.
-	deferToVerify: z
-		.preprocess((v) => (typeof v === "string" ? v === "true" : v), z.boolean())
-		.optional(),
-	messageKey: z.nativeEnum(ResultReason).optional(),
-} satisfies AllKeys<AccessPolicy>);
-
-export const accessPolicyInput = accessPolicyInputShape.superRefine(
-	(policy, ctx) => {
-		if (policy.type !== AccessPolicyType.Block) return;
-		if (policy.captchaType !== undefined) {
-			ctx.addIssue({
-				code: z.ZodIssueCode.custom,
-				path: ["captchaType"],
-				message:
-					"Block policies cannot pin a captchaType — Block always applies to every captcha type. Use a Restrict policy if you want to narrow the effect to one captcha type.",
-			});
-		}
-		if (policy.solvedImagesCount !== undefined) {
-			ctx.addIssue({
-				code: z.ZodIssueCode.custom,
-				path: ["solvedImagesCount"],
-				message:
-					"Block policies cannot set solvedImagesCount — the field only applies to Restrict policies that adjust image-captcha rounds.",
-			});
-		}
-	},
-);
-
-// Historical helper: strip fields the sanitizer used to remove silently.
-// Kept as a no-op-in-practice safety net because Redis records written
-// before the superRefine on `accessPolicyInput` (above) may still carry
-// the stripped fields — reading them back should still normalize to the
-// canonical shape. New writes are rejected at input.
-export const sanitizeAccessPolicy = (policy: AccessPolicy): AccessPolicy => {
-	if (policy.type === AccessPolicyType.Block) {
-		const { captchaType, solvedImagesCount, ...blockPolicy } = policy;
-		return blockPolicy;
-	}
-	return policy;
-};
-
-// `satisfies ZodType<PolicyScope>` is intentionally omitted (matches
-// accessPolicyInput above): the `preprocess` wrapper widens the schema's
-// input type to `unknown`, which fails the `ZodType<T, ZodTypeDef, T>`
-// identity check. The `AllKeys<PolicyScope>` constraint still catches
-// missing-field regressions.
-export const policyScopeInput = z.object({
-	// `getRedisRuleValue` stamps a sentinel string on global rules so the
-	// read-time query can probe `@clientId:{global}` cheaply. Undo the
-	// stamp here so consumers (rankCandidateRules, response payloads,
-	// tests) continue to see `undefined` for global rules — the mongoose
-	// side and the API input side never emit the sentinel.
-	clientId: z.preprocess(
-		(v) => (v === GLOBAL_CLIENT_SCOPE_SENTINEL ? undefined : v),
-		z.coerce.string().optional(),
-	),
-} satisfies AllKeys<PolicyScope>);

package/src/ruleInput/ruleInput.ts

@@ -1,123 +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 } 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 { accessPolicyInputShape, 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;
-	});
-
-// Explicit `ZodType<…, ZodTypeDef, unknown>` annotation rather than the
-// strict-identity form because `accessPolicyInputShape.shape.deferToVerify`
-// uses `z.preprocess` which widens the input position to `unknown`. The
-// relaxed annotation is portable for declaration emit; the `transform`
-// pins the OUTPUT to AccessRule.
-//
-// Uses the unrefined `accessPolicyInputShape` (not `accessPolicyInput`)
-// because the API-write refinement rejecting Block+captchaType is a
-// write-time input guard — the READ path (Redis reader → accessRuleInput
-// parse) must still accept the legacy shapes for records written before
-// the refinement landed. Otherwise the reader would throw on every
-// pre-existing Block rule that carried a stripped captchaType field.
-export const accessRuleInput: ZodType<AccessRule, z.ZodTypeDef, unknown> = z
-	.object({
-		...accessPolicyInputShape.shape,
-		...policyScopeInput.shape,
-	})
-	.and(userScopeInput)
-	.and(ruleGroupInput)
-	.transform((ruleInput: AccessRuleInput): AccessRule => ruleInput);
-
-export const ruleEntryInput: ZodType<AccessRuleEntry, z.ZodTypeDef, unknown> =
-	z.object({
-		rule: accessRuleInput,
-		expiresUnixTimestamp: z.coerce.number().optional(),
-	} satisfies AllKeys<AccessRuleEntry>);
-
-export type AccessRulesFilterInput = AccessRulesFilter & {
-	userScope?: UserScopeInput;
-	policyScopes?: PolicyScope[];
-};
-
-// `satisfies ZodType<AccessRulesFilterInput>` is intentionally omitted:
-// `policyScopeInput.clientId` uses `z.preprocess` to unwrap the Redis
-// `global` sentinel, which widens the input type to `unknown`. The
-// output type is still `AccessRulesFilterInput` (Zod's `_output`); the
-// downstream `DeleteRulesSchema` / `FindRulesSchema` use the relaxed
-// `ZodType<T, ZodTypeDef, unknown>` form for the same reason.
-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(),
-	blockOnly: z.boolean().optional(),
-	includeDeferred: z.boolean().optional(),
-} satisfies AllKeys<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];
-};