osn-selenium 0.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

osn_selenium/javascript/fingerprint/registry/_typehints.py

@@ -0,0 +1,6 @@
+from typing import Literal
+
+
+__all__ = ["ITEM_TYPE_TYPEHINT"]
+
+ITEM_TYPE_TYPEHINT = Literal["method", "prop", "constructor"]

osn_selenium/javascript/fingerprint/registry/_utils.py

@@ -0,0 +1,6 @@
+__all__ = ["MATCH_MEDIA_SETTINGS", "WRAP_ARG_0"]
+
+WRAP_ARG_0 = {"wrapArgIndex": 0}
+MATCH_MEDIA_SETTINGS = {
+	"onReturn": "(mql, eng) => eng.hookMethod(mql, 'addEventListener', 'mediaQuery')"
+}

osn_selenium/javascript/fingerprint/registry/models.py

@@ -0,0 +1,41 @@
+from pydantic import Field
+from typing import Any, Dict, Optional
+from osn_selenium._base_models import DictModel
+from osn_selenium.javascript.fingerprint._typehints import SPOOF_RULE_TYPEHINT
+from osn_selenium.javascript.fingerprint.registry._typehints import ITEM_TYPE_TYPEHINT
+
+
+__all__ = ["RegistryItem"]
+
+
+class RegistryItem(DictModel):
+	"""
+	Represents a single entry in the fingerprint registry, defining how a specific
+	JavaScript API (method, property, or constructor) should be handled.
+
+	Attributes:
+		target (str): The global object or prototype path (e.g., 'window.navigator').
+		name (Optional[str]): The name of the method or property. None for constructors/objects.
+		type_ (ITEM_TYPE): The type of the item ('method', 'prop', 'constructor').
+		api (str): The logical API category (e.g., 'webgl', 'battery').
+		settings (Optional[Dict[str, Any]]): specific configuration for the hook.
+		spoofing_rule (Optional[SPOOF_RULE_TYPEHINT]): The rule used to spoof the return value.
+	"""
+	
+	target: str
+	name: Optional[str] = None
+	type_: ITEM_TYPE_TYPEHINT = Field(alias="type")
+	api: str
+	settings: Optional[Dict[str, Any]] = None
+	spoofing_rule: Optional[SPOOF_RULE_TYPEHINT] = None
+	
+	@property
+	def path(self) -> str:
+		"""
+		Constructs the full path identifier for the registry item.
+
+		Returns:
+			str: The dot-notation path (e.g., 'window.navigator.userAgent').
+		"""
+		
+		return f"{self.target}.{self.name}" if self.name else self.target

osn_selenium/javascript/fingerprint/spoof/__init__.py

@@ -0,0 +1 @@
+

osn_selenium/javascript/fingerprint/spoof/_functions.py

@@ -0,0 +1,172 @@
+from osn_selenium.exceptions.instance import NotExpectedTypeError
+from osn_selenium.javascript._functions import convert_to_js_value
+from osn_selenium.javascript.fingerprint._decorators import indent_code
+from typing import (
+	Any,
+	List,
+	Optional,
+	Sequence,
+	Tuple,
+	Union
+)
+from osn_selenium.javascript.fingerprint._functions import reduce_code_level
+from osn_selenium.javascript.fingerprint.spoof._typehints import NUMBER_TYPEHINT
+from osn_selenium.javascript.fingerprint.spoof.noise import (
+	RandomNoise,
+	StaticNoise
+)
+from osn_selenium.javascript.fingerprint.spoof._templates import (
+	ABSOLUTE_FREQUENCY,
+	ARRAY_GLOBAL_BLOCK,
+	INDEX_CALCULATION_PERIODIC,
+	INDEX_CALCULATION_RAW,
+	INDEX_INCLUSION_LIST_CHECK,
+	INDEX_INCLUSION_SINGLE_CHECK,
+	VARIABLE_FREQUENCY
+)
+
+
+__all__ = [
+	"get_array_global_block_js",
+	"get_frequency_js",
+	"get_index_calculation_js",
+	"get_noise_js",
+	"get_random_expression_js"
+]
+
+
+def get_random_expression_js(value: Union[List[Any], Tuple[NUMBER_TYPEHINT, NUMBER_TYPEHINT]]) -> str:
+	"""
+	Generates JavaScript code to produce a random value based on the input configuration.
+
+	Args:
+		value (Union[List[Any], Tuple[NUMBER, NUMBER]]): A list of options or a tuple representing a numeric range (min, max).
+
+	Returns:
+		str: A JavaScript expression string that evaluates to a random value.
+
+	Raises:
+		TypeError: If the value type is not supported.
+	"""
+	
+	if isinstance(value, tuple) and len(value) == 2:
+		min_val, max_val = value
+	
+		difference = max_val - min_val
+	
+		val1 = str(difference) if difference >= 0 else f"({difference})"
+		operator = "+" if min_val >= 0 else "-"
+		val2 = str(abs(min_val))
+	
+		return f"(Math.random() * {val1} {operator} {val2})"
+	
+	if isinstance(value, list):
+		json_items = convert_to_js_value(value)
+		return f"{json_items}[Math.floor(Math.random() * {len(value)})]"
+	
+	raise NotExpectedTypeError(expected_type=(list, tuple), received_instance=value)
+
+
+def get_noise_js(
+		target: str,
+		noise: str,
+		operation: str,
+		round_result: bool,
+		precision: int
+) -> str:
+	"""
+	Generates JavaScript code to apply noise to a target value.
+
+	Args:
+		target (str): The JavaScript variable/expression to modify.
+		noise (str): The JavaScript expression representing the noise value.
+		operation (str): The operation ('add' or 'multiply').
+		round_result (bool): Whether to round the final result.
+		precision (int): Number of decimal places to keep if rounding.
+
+	Returns:
+		str: A JavaScript expression applying the noise.
+	"""
+	
+	base = f"Number({target})"
+	
+	if operation == "multiply":
+		expr = f"({base} * {noise})"
+	else:
+		expr = f"({base} + {noise})"
+	
+	if round_result:
+		if precision == 0:
+			return f"Math.round({expr})"
+	
+		return f"Math.round({expr} * {precision}) / {precision}"
+	
+	return expr
+
+
+def get_index_calculation_js(cycle_length: Optional[int]) -> str:
+	"""
+	Generates the JavaScript logic for calculating the loop index, optionally handling periodicity.
+
+	Args:
+		cycle_length (Optional[int]): The length of the cycle for periodic modification.
+
+	Returns:
+		str: The JavaScript expression for the current index.
+	"""
+	
+	if cycle_length is None or cycle_length <= 0:
+		return INDEX_CALCULATION_RAW
+	
+	return INDEX_CALCULATION_PERIODIC.format(cycle_length=cycle_length)
+
+
+@indent_code
+def get_frequency_js(frequency_object: Any, expression: str) -> str:
+	"""
+	Generates JavaScript code to conditionally execute an assignment based on frequency/probability.
+
+	Args:
+		frequency_object (Any): An object containing a 'frequency' attribute (e.g., Noise object).
+		expression (str): The JavaScript assignment expression to execute.
+
+	Returns:
+		str: JavaScript code block with probability logic.
+	"""
+	
+	if isinstance(frequency_object, (StaticNoise, RandomNoise)):
+		frequency = frequency_object.frequency
+	else:
+		frequency = 1.0
+	
+	if frequency == 1.0:
+		return ABSOLUTE_FREQUENCY.format(assignment_expression=expression)
+	
+	return VARIABLE_FREQUENCY.format(frequency=frequency, assignment_expression=expression)
+
+
+@indent_code
+def get_array_global_block_js(index_list: Optional[Sequence[int]], frequency_expression: str) -> str:
+	"""
+	Generates the global block logic for array spoofing, checking if indices match specific rules.
+
+	Args:
+		index_list (Optional[Sequence[int]]): specific indices to target, or None for all.
+		frequency_expression (str): The logic to execute if indices match.
+
+	Returns:
+		str: JavaScript code block for the array loop body.
+	"""
+	
+	if index_list is None:
+		return reduce_code_level(code=frequency_expression, num=1)
+	
+	if len(index_list) == 1:
+		index_inclusion_check = INDEX_INCLUSION_SINGLE_CHECK.format(channel_index=index_list[0])
+	else:
+		index_inclusion_check = INDEX_INCLUSION_LIST_CHECK.format(index_list=",".join(map(str, index_list)))
+	
+	return ARRAY_GLOBAL_BLOCK.format(
+			index_inclusion_check=index_inclusion_check,
+			frequency_logic=frequency_expression
+	)

osn_selenium/javascript/fingerprint/spoof/_templates.py

@@ -0,0 +1,134 @@
+__all__ = [
+	"ABSOLUTE_FREQUENCY",
+	"ARRAY_CHANNEL_BLOCK",
+	"ARRAY_GLOBAL_BLOCK",
+	"ARRAY_LOOP_WRAPPER",
+	"CUSTOM_RULE",
+	"INDEX_CALCULATION_PERIODIC",
+	"INDEX_CALCULATION_RAW",
+	"INDEX_INCLUSION_LIST_CHECK",
+	"INDEX_INCLUSION_SINGLE_CHECK",
+	"PERSISTED_RANDOM_ITEM_NOISE",
+	"PERSISTED_RANDOM_ITEM_SET",
+	"PERSISTENCE_CHECK_NOISE",
+	"PERSISTENCE_CHECK_RETURN",
+	"PERSISTENCE_SAVE_NOISE",
+	"PERSISTENCE_SAVE_RESULT",
+	"RANDOM_ITEM_NOISE",
+	"RANDOM_ITEM_SET",
+	"STATIC_ITEM_NOISE",
+	"STATIC_ITEM_SET",
+	"VARIABLE_FREQUENCY"
+]
+
+CUSTOM_RULE = """
+(originalValue, args) => {{
+	{custom_javascript_code}
+}}
+""".strip("\n")
+
+STATIC_ITEM_SET = """
+(originalValue) => {{
+	return {result_value};
+}}
+""".strip("\n")
+
+STATIC_ITEM_NOISE = """
+(originalValue) => {{
+	return {math_expression};
+}}
+""".strip("\n")
+
+RANDOM_ITEM_SET = """
+(originalValue) => {{
+	const randomResult = {calculation_expression};
+
+	return randomResult;
+}}
+""".strip("\n")
+
+PERSISTED_RANDOM_ITEM_SET = """
+(originalValue) => {{
+{persistence_check_code}
+	const randomResult = {calculation_expression};
+	{persistence_save_code}
+
+	return randomResult;
+}}
+""".strip("\n")
+
+RANDOM_ITEM_NOISE = """
+(originalValue) => {{
+	const noiseValue = {calculation_expression};
+
+	return {math_expression};
+}}
+""".strip("\n")
+
+PERSISTED_RANDOM_ITEM_NOISE = """
+(originalValue) => {{
+{persistence_check_code}
+	const noiseValue = {calculation_expression};
+	{persistence_save_code}
+
+	return {math_expression};
+}}
+""".strip("\n")
+
+PERSISTENCE_CHECK_RETURN = """
+if (STORAGE.has('{storage_key}')) {{
+	return STORAGE.get('{storage_key}');
+}}
+""".strip("\n")
+PERSISTENCE_SAVE_RESULT = "STORAGE.set('{storage_key}', randomResult);"
+
+PERSISTENCE_CHECK_NOISE = """
+if (STORAGE.has('{storage_key}')) {{
+	const noiseValue = STORAGE.get('{storage_key}');
+
+	return {math_expression_with_noise};
+}}
+""".strip("\n")
+PERSISTENCE_SAVE_NOISE = "STORAGE.set('{storage_key}', noiseValue);"
+
+ARRAY_LOOP_WRAPPER = """
+(originalObject) => {{
+	const dataArray = originalObject.data || originalObject;
+
+	for (let i = 0; i < dataArray.length; i++) {{
+		const indexInCycle = {index_calculation};
+
+{loop_body_logic}
+	}}
+
+	return originalObject;
+}}
+""".strip("\n")
+
+ARRAY_CHANNEL_BLOCK = """
+if (indexInCycle === {target_index}) {{
+{frequency_logic}
+
+	continue;
+}}
+""".strip("\n")
+
+ARRAY_GLOBAL_BLOCK = """
+if ({index_inclusion_check}) {{
+{frequency_logic}
+}}
+""".strip("\n")
+
+INDEX_CALCULATION_RAW = "i"
+INDEX_CALCULATION_PERIODIC = "i % {cycle_length}"
+
+VARIABLE_FREQUENCY = """
+if (Math.random() <= {frequency}) {{
+	dataArray[i] = {assignment_expression};
+}}
+""".strip("\n")
+
+ABSOLUTE_FREQUENCY = "dataArray[i] = {assignment_expression};"
+
+INDEX_INCLUSION_LIST_CHECK = "[{index_list}].includes(indexInCycle)"
+INDEX_INCLUSION_SINGLE_CHECK = "indexInCycle === {channel_index}"

osn_selenium/javascript/fingerprint/spoof/_typehints.py

@@ -0,0 +1,22 @@
+from typing import (
+	Any,
+	List,
+	Tuple,
+	Union
+)
+
+
+__all__ = [
+	"NOISE_TYPEHINT",
+	"NUMBER_TYPEHINT",
+	"RANDOM_NOISE_TYPEHINT",
+	"RANDOM_NUMBER_TYPEHINT",
+	"RANDOM_VALUE_TYPEHINT"
+]
+
+NUMBER_TYPEHINT = Union[int, float]
+RANDOM_NUMBER_TYPEHINT = Tuple[NUMBER_TYPEHINT, NUMBER_TYPEHINT]
+NOISE_TYPEHINT = Union[NUMBER_TYPEHINT]
+
+RANDOM_NOISE_TYPEHINT = Union[List[NOISE_TYPEHINT], RANDOM_NUMBER_TYPEHINT]
+RANDOM_VALUE_TYPEHINT = Union[List[Any], RANDOM_NUMBER_TYPEHINT]

osn_selenium/javascript/fingerprint/spoof/core_rules.py

@@ -0,0 +1,141 @@
+from osn_selenium._base_models import DictModel
+from pydantic import (
+	Field,
+	model_validator
+)
+from typing import (
+	Any,
+	Callable,
+	Dict,
+	List,
+	Optional,
+	Self
+)
+from osn_selenium.javascript.fingerprint._functions import add_code_level
+from osn_selenium.exceptions.logic import (
+	AbstractImplementationError
+)
+from osn_selenium.javascript.fingerprint.spoof._templates import (
+	ARRAY_CHANNEL_BLOCK,
+	ARRAY_LOOP_WRAPPER
+)
+from osn_selenium.javascript.fingerprint.spoof._functions import (
+	get_array_global_block_js,
+	get_frequency_js,
+	get_index_calculation_js
+)
+
+
+__all__ = ["ArrayRule", "BaseRule", "RandomRule"]
+
+
+class BaseRule(DictModel):
+	"""
+	Abstract base class for all spoofing rules.
+
+	Attributes:
+		mode (str): The identifier for the rule type.
+		value (Any): The value associated with the rule.
+	"""
+	
+	mode: str
+	value: Any
+	
+	def generate_js(self, path: str) -> str:
+		"""
+		Generates the JavaScript implementation for this rule.
+
+		Args:
+			path (str): The object path where the rule applies.
+
+		Returns:
+			str: The generated JavaScript code.
+
+		Raises:
+			NotImplementedError: Must be implemented by subclasses.
+		"""
+		
+		raise AbstractImplementationError(method_name="generate_js", class_name=self.__class__.__name__)
+
+
+class RandomRule(BaseRule):
+	"""
+	Base class for rules involving random value generation with optional persistence.
+
+	Attributes:
+		mode (str): The identifier for the rule type.
+		value (Any): The value associated with the rule.
+		persist (bool): Whether to store and reuse the generated random value.
+	"""
+	
+	persist: bool = False
+
+
+class ArrayRule(BaseRule):
+	"""
+	Base class for rules that modify array contents.
+
+	Attributes:
+		mode (str): The identifier for the rule type.
+		value (Any): The value associated with the rule.
+		cycle_length (Optional[int]): Length of the cycle for periodic modification.
+		index_list (Optional[List[int]]): Specific indices to target globally.
+		value_by_channel (Dict[int, Any]): Specific values for specific indices.
+	"""
+	
+	cycle_length: Optional[int] = None
+	index_list: Optional[List[int]] = None
+	value_by_channel: Dict[int, Any] = Field(default_factory=dict)
+	
+	@model_validator(mode="after")
+	def _cleanup_channels(self) -> Self:
+		"""
+		Validates and cleans up the index list to avoid conflicts with explicit channels.
+
+		Returns:
+			Self: The validated model.
+		"""
+		
+		if self.index_list is not None and self.value_by_channel:
+			exclusive_channels = set(self.value_by_channel.keys())
+			self.index_list = [c for c in self.index_list if c not in exclusive_channels]
+		
+		return self
+	
+	def _generate_array_js(self, get_expression_fn: Callable[[Any], str]) -> str:
+		"""
+		Helper to generate the array looping and modification logic.
+
+		Args:
+			get_expression_fn (Callable[[Any], str]): Function to convert a value/noise item into a JS expression.
+
+		Returns:
+			str: The complete JavaScript code for the array wrapper.
+		"""
+		
+		body_parts = []
+		
+		if self.value_by_channel:
+			for ch, item in self.value_by_channel.items():
+				expression = get_expression_fn(item)
+				frequency_expression = get_frequency_js(frequency_object=item, expression=expression)
+		
+				body_parts.append(
+						add_code_level(
+								code=ARRAY_CHANNEL_BLOCK.format(target_index=ch, frequency_logic=frequency_expression),
+								num=1
+						)
+				)
+		
+		if self.value is not None:
+			expression = get_expression_fn(self.value)
+			frequency_expression = get_frequency_js(frequency_object=self.value, expression=expression)
+		
+			body_parts.append(
+					get_array_global_block_js(index_list=self.index_list, frequency_expression=frequency_expression)
+			)
+		
+		return ARRAY_LOOP_WRAPPER.format(
+				index_calculation=get_index_calculation_js(cycle_length=self.cycle_length),
+				loop_body_logic=add_code_level(code="\n".join(body_parts), num=1)
+		)

osn_selenium/javascript/fingerprint/spoof/noise.py

@@ -0,0 +1,51 @@
+from pydantic import Field
+from typing import Any, Literal
+from osn_selenium._base_models import DictModel
+from osn_selenium.javascript.fingerprint.spoof._typehints import (
+	NOISE_TYPEHINT,
+	RANDOM_NOISE_TYPEHINT
+)
+
+
+__all__ = ["BaseNoise", "RandomNoise", "StaticNoise"]
+
+
+class BaseNoise(DictModel):
+	"""
+	Base configuration for noise generation.
+
+	Attributes:
+		value (Any): The base value or range for the noise.
+		frequency (float): Probability of applying the noise (0.0 to 1.0).
+		operation (Literal["add", "multiply"]): Mathematical operation to apply noise.
+		round (bool): Whether to round the result.
+		precision (int): Decimal precision if rounding is enabled.
+	"""
+	
+	value: Any
+	frequency: float = Field(default=1.0, gt=0.0, le=1.0)
+	operation: Literal["add", "multiply"] = "add"
+	round: bool = False
+	precision: int = Field(default=0, ge=0)
+
+
+class StaticNoise(BaseNoise):
+	"""
+	Configuration for static (constant) noise.
+
+	Attributes:
+		value (NOISE): A single numeric value to use as noise.
+	"""
+	
+	value: NOISE_TYPEHINT
+
+
+class RandomNoise(BaseNoise):
+	"""
+	Configuration for random noise generation.
+
+	Attributes:
+		value (RANDOM_NOISE): A range (tuple) or list of values to pick from.
+	"""
+	
+	value: RANDOM_NOISE_TYPEHINT