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

osn_selenium/javascript/fingerprint/_detect/functions.py

@@ -0,0 +1,253 @@
+from typing import Optional
+from osn_selenium.javascript.fingerprint._decorators import indent_code
+from osn_selenium.javascript.fingerprint._functions import add_code_level
+from osn_selenium.javascript.fingerprint.registry.models import RegistryItem
+from osn_selenium.javascript.fingerprint._detect.templates import (
+	ARG_WRAPPER_LOGIC,
+	CALL_ORIGINAL_METHOD,
+	CALL_ORIGINAL_PROP,
+	DESCRIPTOR_LOOKUP_METHOD,
+	DESCRIPTOR_LOOKUP_PROP,
+	HOOK_IIFE_WRAPPER,
+	METADATA_PRESERVATION,
+	PART_ARG_WRAPPER,
+	PART_REPORT,
+	PART_SPOOF_METHOD,
+	PART_SPOOF_PROP,
+	REPORT_LOGIC,
+	TARGET_RESOLUTION,
+	WRAPPER_CONSTRUCTOR_SKELETON,
+	WRAPPER_METHOD_SKELETON,
+	WRAPPER_PROP_SKELETON
+)
+
+
+__all__ = [
+	"build_function_body",
+	"get_arg_wrapper_js",
+	"get_constructor_hook_body",
+	"get_hook_js",
+	"get_method_hook_body",
+	"get_prop_hook_body"
+]
+
+
+def build_function_body(
+		report_js: str,
+		arg_wrapper_js: Optional[str],
+		call_original: Optional[str],
+		spoof_path: Optional[str],
+		is_method: bool,
+		indent_level: int,
+) -> str:
+	"""
+	Constructs the internal body of a hook function in JavaScript.
+
+	Args:
+		report_js (str): The JavaScript code for reporting.
+		arg_wrapper_js (Optional[str]): The JavaScript code for argument wrapping.
+		call_original (Optional[str]): The JavaScript code to call the original method/property.
+		spoof_path (Optional[str]): The path key for looking up spoofing modifiers.
+		is_method (bool): True if building a method hook, False for a property hook.
+		indent_level (int): The indentation level to apply to the generated code.
+
+	Returns:
+		str: The indented JavaScript function body.
+	"""
+	
+	parts = []
+	
+	if report_js:
+		parts.append(PART_REPORT.format(report_logic=report_js))
+	
+	if arg_wrapper_js:
+		parts.append(PART_ARG_WRAPPER.format(arg_wrapper_logic=arg_wrapper_js))
+	
+	if call_original:
+		parts.append(call_original)
+	
+	if spoof_path:
+		template = PART_SPOOF_METHOD if is_method else PART_SPOOF_PROP
+		parts.append(template.format(path=spoof_path))
+	
+	raw_body = "\n".join(parts)
+	
+	return add_code_level(code=raw_body, num=indent_level)
+
+
+@indent_code
+def get_constructor_hook_body(target: str, report_js: str, arg_wrapper_js: str) -> str:
+	"""
+	Generates the body of a constructor hook.
+
+	Args:
+		target (str): The JS target class name.
+		report_js (str): JavaScript code for reporting usage.
+		arg_wrapper_js (str): JavaScript code for wrapping arguments.
+
+	Returns:
+		str: The complete JavaScript code for hooking the constructor via Proxy.
+	"""
+	
+	resolution = f"const originalClass = window['{target}'];\nif (!originalClass) return;"
+	
+	wrapper_body = build_function_body(
+			report_js=report_js,
+			arg_wrapper_js=arg_wrapper_js,
+			call_original=None,
+			spoof_path=None,
+			is_method=True,
+			indent_level=2,
+	)
+	
+	wrapper = WRAPPER_CONSTRUCTOR_SKELETON.format(class_name=target, wrapper_body=wrapper_body)
+	
+	return f"{resolution}\n\n{wrapper}"
+
+
+@indent_code
+def get_prop_hook_body(target: str, name: str, report_js: str, spoof_path: Optional[str]) -> str:
+	"""
+	Generates the body of a property getter hook.
+
+	Args:
+		target (str): The JS target object (e.g., 'window').
+		name (str): The name of the property.
+		report_js (str): JavaScript code for reporting usage.
+		spoof_path (Optional[str]): Path key for spoofing logic, if enabled.
+
+	Returns:
+		str: The complete JavaScript code for hooking the property.
+	"""
+	
+	lookup = DESCRIPTOR_LOOKUP_PROP.format(prop_name=name)
+	resolution = TARGET_RESOLUTION.format(target_object=target, descriptor_lookup=lookup)
+	
+	wrapper_body = build_function_body(
+			report_js=report_js,
+			arg_wrapper_js=None,
+			call_original=CALL_ORIGINAL_PROP,
+			spoof_path=spoof_path,
+			is_method=False,
+			indent_level=1,
+	)
+	
+	wrapper = WRAPPER_PROP_SKELETON.format(prop_name=name, wrapper_body=wrapper_body)
+	
+	return f"{resolution}\n\n{wrapper}"
+
+
+@indent_code
+def get_method_hook_body(
+		target: str,
+		name: str,
+		report_js: str,
+		arg_wrapper_js: str,
+		spoof_path: Optional[str]
+) -> str:
+	"""
+	Generates the body of a method hook.
+
+	Args:
+		target (str): The JS target object.
+		name (str): The name of the method.
+		report_js (str): JavaScript code for reporting usage.
+		arg_wrapper_js (str): JavaScript code for wrapping arguments.
+		spoof_path (Optional[str]): Path key for spoofing logic, if enabled.
+
+	Returns:
+		str: The complete JavaScript code for hooking the method.
+	"""
+	
+	lookup = DESCRIPTOR_LOOKUP_METHOD.format(method_name=name)
+	resolution = TARGET_RESOLUTION.format(target_object=target, descriptor_lookup=lookup)
+	
+	wrapper_body = build_function_body(
+			report_js=report_js,
+			arg_wrapper_js=arg_wrapper_js,
+			call_original=CALL_ORIGINAL_METHOD,
+			spoof_path=spoof_path,
+			is_method=True,
+			indent_level=1,
+	)
+	
+	wrapper = WRAPPER_METHOD_SKELETON.format(method_name=name, wrapper_body=wrapper_body)
+	metadata = METADATA_PRESERVATION.format(method_name=name)
+	
+	return f"{resolution}\n\n{wrapper}\n\n{metadata}"
+
+
+@indent_code
+def get_arg_wrapper_js(entry: RegistryItem) -> str:
+	"""
+	Generates JavaScript code to wrap arguments if required by the registry entry.
+
+	Args:
+		entry (RegistryItem): The registry item containing configuration settings.
+
+	Returns:
+		str: The JavaScript code for argument wrapping, or an empty string if not applicable.
+	"""
+	
+	if entry.settings is None:
+		return ""
+	
+	index = entry.settings.get("wrapArgIndex")
+	
+	if index is None:
+		return ""
+	
+	return ARG_WRAPPER_LOGIC.format(index=index, api=entry.api, name=entry.name or "constructor")
+
+
+def get_hook_js(path: str, entry: RegistryItem, is_detected: bool, is_spoofed: bool) -> str:
+	"""
+	Generates the full IIFE JavaScript hook for a given registry entry.
+
+	Args:
+		path (str): The unique path identifier for the hook.
+		entry (RegistryItem): The registry item configuration.
+		is_detected (bool): Whether to include detection/reporting logic.
+		is_spoofed (bool): Whether to include spoofing logic.
+
+	Returns:
+		str: The generated JavaScript code wrapped in an IIFE guard.
+	"""
+	
+	spoof_path = path if is_spoofed else None
+	
+	report_js = ""
+	arg_wrapper_js = ""
+	
+	if is_detected:
+		name = entry.name if entry.name else "constructor"
+		report_js = REPORT_LOGIC.format(api=entry.api, target=entry.target, name=name)
+	
+		if entry.type_ in ("method", "constructor"):
+			arg_wrapper_js = get_arg_wrapper_js(entry=entry)
+	
+	if entry.type_ == "method":
+		hook_body = get_method_hook_body(
+				target=entry.target,
+				name=entry.name,
+				report_js=report_js,
+				arg_wrapper_js=arg_wrapper_js,
+				spoof_path=spoof_path,
+		)
+	elif entry.type_ == "prop":
+		hook_body = get_prop_hook_body(
+				target=entry.target,
+				name=entry.name,
+				report_js=report_js,
+				spoof_path=spoof_path,
+		)
+	elif entry.type_ == "constructor":
+		hook_body = get_constructor_hook_body(
+				target=entry.target,
+				report_js=report_js,
+				arg_wrapper_js=arg_wrapper_js,
+		)
+	else:
+		return ""
+	
+	return HOOK_IIFE_WRAPPER.format(hook_body=add_code_level(code=hook_body, num=1))

osn_selenium/javascript/fingerprint/_detect/templates.py

@@ -0,0 +1,128 @@
+__all__ = [
+	"ARG_WRAPPER_LOGIC",
+	"CALL_ORIGINAL_METHOD",
+	"CALL_ORIGINAL_PROP",
+	"DESCRIPTOR_LOOKUP_METHOD",
+	"DESCRIPTOR_LOOKUP_PROP",
+	"HOOK_IIFE_WRAPPER",
+	"METADATA_PRESERVATION",
+	"PART_ARG_WRAPPER",
+	"PART_REPORT",
+	"PART_SPOOF_METHOD",
+	"PART_SPOOF_PROP",
+	"REPORT_LOGIC",
+	"TARGET_RESOLUTION",
+	"WRAPPER_CONSTRUCTOR_SKELETON",
+	"WRAPPER_METHOD_SKELETON",
+	"WRAPPER_PROP_SKELETON"
+]
+
+HOOK_IIFE_WRAPPER = """
+guard(
+	() => {{
+{hook_body}
+	}}
+);
+""".strip("\n")
+
+TARGET_RESOLUTION = """
+const target = ({target_object}.prototype || {target_object});
+let descriptor, current = target;
+
+{descriptor_lookup}
+""".strip("\n")
+
+DESCRIPTOR_LOOKUP_METHOD = """
+let original;
+try {{ original = target['{method_name}']; }} catch(e) {{ return; }}
+
+if (!original || typeof original !== 'function' || hookedRegistry.has(original)) return;
+""".strip("\n")
+
+DESCRIPTOR_LOOKUP_PROP = """
+while (current && !descriptor) {{
+	descriptor = Object.getOwnPropertyDescriptor(current, '{prop_name}');
+	current = Object.getPrototypeOf(current);
+}}
+
+if (!descriptor || !descriptor.get || hookedRegistry.has(descriptor.get)) return;
+
+const originalGet = descriptor.get;
+""".strip("\n")
+
+WRAPPER_METHOD_SKELETON = """
+const wrapper = function(...args) {{
+{wrapper_body}
+
+	return result;
+}};
+
+hookedRegistry.add(wrapper);
+hookedRegistry.add(original);
+
+target['{method_name}'] = wrapper;
+""".strip("\n")
+
+WRAPPER_PROP_SKELETON = """
+const wrapperGet = function() {{
+{wrapper_body}
+
+	return result;
+}};
+
+hookedRegistry.add(wrapperGet);
+hookedRegistry.add(originalGet);
+
+Object.defineProperty(
+	target,
+	'{prop_name}',
+	{{
+		...descriptor,
+		get: wrapperGet
+	}}
+);
+""".strip("\n")
+
+WRAPPER_CONSTRUCTOR_SKELETON = """
+if (hookedRegistry.has(originalClass)) return;
+
+const handler = {{
+	construct(target, args) {{
+{wrapper_body}
+
+		return new target(...args);
+	}}
+}};
+
+try {{
+	const wrapped = new Proxy(originalClass, handler);
+	window['{class_name}'] = wrapped;
+	hookedRegistry.add(wrapped);
+}} catch (e) {{}}
+""".strip("\n")
+
+METADATA_PRESERVATION = """
+try {{ Object.defineProperty(wrapper, 'name', {{ value: '{method_name}' }}); }} catch (e) {{}}
+try {{ Object.defineProperty(wrapper, 'toString', {{ value: () => original.toString() }}); }} catch (e) {{}}
+""".strip("\n")
+
+CALL_ORIGINAL_METHOD = "let result; try { result = original.apply(this, args); } catch(e) {}"
+CALL_ORIGINAL_PROP = "let result; try { result = originalGet.call(this); } catch(e) {}"
+
+PART_REPORT = "{report_logic}"
+PART_ARG_WRAPPER = "{arg_wrapper_logic}"
+PART_SPOOF_METHOD = "if (MODIFIERS['{path}']) {{ result = MODIFIERS['{path}'](result, args); }}"
+PART_SPOOF_PROP = "if (MODIFIERS['{path}']) {{ result = MODIFIERS['{path}'](result); }}"
+
+REPORT_LOGIC = "Reporter.send('{api}', '{target}', '{name}');"
+
+ARG_WRAPPER_LOGIC = """
+if (typeof args[{index}] === 'function') {{
+	const origCb = args[{index}];
+
+	args[{index}] = function(...cbArgs) {{
+		Reporter.send('{api}', '{name}_cb');
+		return origCb.apply(this, cbArgs);
+	}};
+}}
+""".strip("\n")

osn_selenium/javascript/fingerprint/_functions.py

@@ -0,0 +1,35 @@
+__all__ = ["add_code_level", "reduce_code_level"]
+
+
+def reduce_code_level(code: str, num: int = 1) -> str:
+	"""
+	Reduces the indentation level of a multi-line string by removing leading tabs.
+
+	Args:
+		code (str): The code block to un-indent.
+		num (int): The number of tabs to remove. Defaults to 1.
+
+	Returns:
+		str: The un-indented code.
+	"""
+	
+	reducing = "\t" * num
+	
+	return "\n".join([line.removeprefix(reducing) for line in code.splitlines()])
+
+
+def add_code_level(code: str, num: int = 1) -> str:
+	"""
+	Increases the indentation level of a multi-line string by adding leading tabs.
+
+	Args:
+		code (str): The code block to indent.
+		num (int): The number of tabs to add. Defaults to 1.
+
+	Returns:
+		str: The indented code.
+	"""
+	
+	adding = "\t" * num
+	
+	return adding + f"\n{adding}".join(code.splitlines())

osn_selenium/javascript/fingerprint/_typehints.py

@@ -0,0 +1,27 @@
+from typing import Union
+from osn_selenium.javascript.fingerprint.spoof.rules import (
+	CustomRule,
+	RandomArrayNoiseRule,
+	RandomArraySetRule,
+	RandomItemNoiseRule,
+	RandomItemSetRule,
+	StaticArrayNoiseRule,
+	StaticArraySetRule,
+	StaticItemNoiseRule,
+	StaticItemSetRule
+)
+
+
+__all__ = ["SPOOF_RULE_TYPEHINT"]
+
+SPOOF_RULE_TYPEHINT = Union[
+	StaticItemSetRule,
+	RandomItemSetRule,
+	StaticArraySetRule,
+	RandomArraySetRule,
+	StaticItemNoiseRule,
+	RandomItemNoiseRule,
+	StaticArrayNoiseRule,
+	RandomArrayNoiseRule,
+	CustomRule
+]

osn_selenium/javascript/fingerprint/registry/__init__.py

@@ -0,0 +1,7 @@
+from osn_selenium.javascript.fingerprint.registry.models import RegistryItem
+from osn_selenium.javascript.fingerprint.registry._functions import create_registry
+
+
+__all__ = ["FINGERPRINT_REGISTRY", "RegistryItem"]
+
+FINGERPRINT_REGISTRY = create_registry()

osn_selenium/javascript/fingerprint/registry/_core_functions.py

@@ -0,0 +1,236 @@
+from typing import (
+	Any,
+	Dict,
+	Iterable,
+	Mapping,
+	Optional
+)
+from osn_selenium.javascript.fingerprint.registry.models import RegistryItem
+from osn_selenium.javascript.fingerprint.registry._typehints import ITEM_TYPE_TYPEHINT
+
+
+__all__ = [
+	"register",
+	"register_key_methods",
+	"register_keys_methods",
+	"register_target_methods",
+	"register_targets",
+	"register_targets_methods"
+]
+
+
+def register(
+		registry: Dict[str, RegistryItem],
+		target: str,
+		key: str,
+		type_: ITEM_TYPE_TYPEHINT,
+		api: str,
+		method: Optional[str],
+		settings: Optional[Dict[str, Any]] = None
+) -> Dict[str, RegistryItem]:
+	"""
+	Registers a single item into the registry.
+
+	Args:
+		registry (Dict[str, RegistryItem]): The registry dictionary to update.
+		target (str): The JavaScript target object/class.
+		key (str): The unique key for the registry entry.
+		type_ (ITEM_TYPE): The type of hook ('method', 'prop', 'constructor').
+		api (str): The API category name.
+		method (Optional[str]): The name of the method/property, or None.
+		settings (Optional[Dict[str, Any]]): Additional configuration settings.
+
+	Returns:
+		Dict[str, RegistryItem]: The updated registry dictionary.
+	"""
+	
+	registry[key] = RegistryItem(target=target, name=method, type=type_, api=api, settings=settings)
+	
+	return registry
+
+
+def register_targets_methods(
+		registry: Dict[str, RegistryItem],
+		targets: Iterable[str],
+		type_: ITEM_TYPE_TYPEHINT,
+		api: str,
+		methods: Iterable[str],
+		settings: Optional[Dict[str, Any]] = None
+) -> Dict[str, RegistryItem]:
+	"""
+	Registers multiple methods for multiple targets.
+
+	Args:
+		registry (Dict[str, RegistryItem]): The registry to update.
+		targets (Iterable[str]): A list of target objects.
+		type_ (ITEM_TYPE): The type of the items.
+		api (str): The API category.
+		methods (Iterable[str]): A list of methods to register for each target.
+		settings (Optional[Dict[str, Any]]): Configuration settings.
+
+	Returns:
+		Dict[str, RegistryItem]: The updated registry.
+	"""
+	
+	for target in targets:
+		for method in methods:
+			registry = register(
+					registry=registry,
+					key=f"{target}.{method}",
+					target=target,
+					type_=type_,
+					api=api,
+					method=method,
+					settings=settings
+			)
+	
+	return registry
+
+
+def register_targets(
+		registry: Dict[str, RegistryItem],
+		targets: Iterable[str],
+		type_: ITEM_TYPE_TYPEHINT,
+		api: str,
+		settings: Optional[Dict[str, Any]] = None
+) -> Dict[str, RegistryItem]:
+	"""
+	Registers multiple targets directly without specific methods.
+
+	Args:
+		registry (Dict[str, RegistryItem]): The registry to update.
+		targets (Iterable[str]): A list of target objects.
+		type_ (ITEM_TYPE): The type of the items.
+		api (str): The API category.
+		settings (Optional[Dict[str, Any]]): Configuration settings.
+
+	Returns:
+		Dict[str, RegistryItem]: The updated registry.
+	"""
+	
+	for target in targets:
+		registry = register(
+				registry=registry,
+				key=target,
+				target=target,
+				type_=type_,
+				api=api,
+				method=None,
+				settings=settings
+		)
+	
+	return registry
+
+
+def register_target_methods(
+		registry: Dict[str, RegistryItem],
+		target: str,
+		type_: ITEM_TYPE_TYPEHINT,
+		api: str,
+		methods: Iterable[str],
+		settings: Optional[Dict[str, Any]] = None
+) -> Dict[str, RegistryItem]:
+	"""
+	Registers multiple methods for a single target.
+
+	Args:
+		registry (Dict[str, RegistryItem]): The registry to update.
+		target (str): The target object.
+		type_ (ITEM_TYPE): The type of the items.
+		api (str): The API category.
+		methods (Iterable[str]): A list of methods/properties to register.
+		settings (Optional[Dict[str, Any]]): Configuration settings.
+
+	Returns:
+		Dict[str, RegistryItem]: The updated registry.
+	"""
+	
+	for method in methods:
+		registry = register(
+				registry=registry,
+				key=f"{target}.{method}",
+				target=target,
+				type_=type_,
+				api=api,
+				method=method,
+				settings=settings
+		)
+	
+	return registry
+
+
+def register_keys_methods(
+		registry: Dict[str, RegistryItem],
+		keys: Mapping[str, str],
+		type_: ITEM_TYPE_TYPEHINT,
+		api: str,
+		methods: Iterable[str],
+		settings: Optional[Dict[str, Any]] = None
+) -> Dict[str, RegistryItem]:
+	"""
+	Registers methods for multiple targets defined by a mapping of keys to targets.
+
+	Args:
+		registry (Dict[str, RegistryItem]): The registry to update.
+		keys (Mapping[str, str]): Map where key is the registry key prefix and value is the target object.
+		type_ (ITEM_TYPE): The type of the items.
+		api (str): The API category.
+		methods (Iterable[str]): A list of methods to register.
+		settings (Optional[Dict[str, Any]]): Configuration settings.
+
+	Returns:
+		Dict[str, RegistryItem]: The updated registry.
+	"""
+	
+	for key, target in keys.items():
+		for method in methods:
+			registry = register(
+					registry=registry,
+					key=f"{key}.{method}",
+					target=target,
+					type_=type_,
+					api=api,
+					method=method,
+					settings=settings
+			)
+	
+	return registry
+
+
+def register_key_methods(
+		registry: Dict[str, RegistryItem],
+		key: str,
+		target: str,
+		type_: ITEM_TYPE_TYPEHINT,
+		api: str,
+		methods: Iterable[str],
+		settings: Optional[Dict[str, Any]] = None
+) -> Dict[str, RegistryItem]:
+	"""
+	Registers multiple methods for a single target using a custom key prefix.
+
+	Args:
+		registry (Dict[str, RegistryItem]): The registry to update.
+		key (str): The prefix to use for the registry keys.
+		target (str): The target object.
+		type_ (ITEM_TYPE): The type of the items.
+		api (str): The API category.
+		methods (Iterable[str]): A list of methods to register.
+		settings (Optional[Dict[str, Any]]): Configuration settings.
+
+	Returns:
+		Dict[str, RegistryItem]: The updated registry.
+	"""
+	
+	for method in methods:
+		registry = register(
+				registry=registry,
+				key=f"{key}.{method}",
+				target=target,
+				type_=type_,
+				api=api,
+				method=method,
+				settings=settings
+		)
+	
+	return registry