ProxyPin

ProxyPin is an open-source, free HTTP(S) traffic capture tool that supports Windows, Mac, Android, iOS, and Linux. It is built with Flutter and is designed to intercept, inspect, and rewrite HTTP(S) traffic, including traffic from Flutter applications.

Core Capabilities:

• Mobile QR Code Connection: Connect devices via QR code scanning to avoid manual Wi-Fi proxy configuration and synchronization.
• Domain Filtering: Intercept only specific traffic to avoid interference from other applications.
• Search: Search requests using keywords and various response type conditions.
• Scripting: Use JavaScript to process requests or responses.
• Request Rewriting: Supports redirection, replacing request/response bodies, or modifying them based on specific rules.
• Request Mapping: Use local configurations or scripts to respond to requests instead of hitting remote services.
• Request Decryption: Automatically decrypt HTTP message bodies by configuring AES decryption keys.
• Request Blocking: Block requests based on URL to prevent them from reaching the server.
• History & Export: Automatically saves traffic data for review. Supports importing and exporting in HAR format.
• Utilities: Includes favorites, a toolbox, common encoding tools, QR code generation, and regex support.

The CertificateManager class provides a centralized way to handle CA (Certificate Authority) roots, generate leaf certificates for specific hosts, and manage security contexts for HTTPS interception. It maintains an internal cache of SecurityContext objects to optimize performance.

Key capabilities include:

• Automatic CA Initialization: Loading the root CA and private key from the application support directory.
• Leaf Certificate Generation: Creating self-signed certificates for specific domains to allow traffic interception.
• Remote Certificate Mimicry: Regenerating leaf certificates based on real remote server certificates to bypass strict client-side validation (e.g., matching Subject, SAN, and validity periods).
• PKCS#12 Support: Exporting and importing certificates via .p12 files.

import 'package:proxypin/network/util/crts.dart';

// Example: Get a security context for a specific host
SecurityContext? context = CertificateManager.get('www.example.com');

// Example: Get or initialize a context for a host
SecurityContext context = await CertificateManager.getCertificateContext('www.example.com');

The NetworkConditionInterceptor is used to inject network impairments into the HTTP request/response lifecycle. It allows you to simulate real-world scenarios such as high latency, packet loss, offline states, and bandwidth throttling (upload/download speeds).

Key Behaviors

• Offline Mode: If the resolved condition is set to offline, the interceptor returns null, preventing the request from being sent and simulating a connection failure.
• Packet Loss: If lossRate is configured, the interceptor may randomly discard the entire request/response, returning a synthesized 502 status code with the header X-ProxyPin-Weak-Network: loss to simulate connection timeouts or failures.
• Latency & Jitter: Applies a base latency (requestLatencyMs or responseLatencyMs) plus a random jitterMs to the request or response.
• Bandwidth Throttling: Calculates additional delay based on the body size and the configured uploadKbps (for requests) or downloadKbps (for responses). The formula used is (bytes * 8 / kbps) to convert kilobits per second to milliseconds.

Lifecycle Integration

• onRequest: Applies request latency, jitter, and upload throttling.
• onResponse: Applies response latency, jitter, and download throttling.
• execute: Handles the short-circuiting logic for offline and lossRate scenarios.

Note: The interceptor has a priority of 1100, ensuring it runs after standard blocking interceptors (which typically have a priority of 1000).

import 'package:proxypin/network/components/network_condition.dart';

// Access the singleton instance
final interceptor = NetworkConditionInterceptor.instance;

ProxyPin supports dynamic string replacement using the {{name}} syntax. This is useful for injecting environment variables into rewrite rules or scripts.

• Syntax: {{variable_name}}. The name can contain alphanumeric characters, underscores, dots, or hyphens. Whitespace inside the braces is allowed (e.g., {{ name }}).
• Resolution Logic: The manager attempts to find the variable in the active environment first, then the global environment. If the variable is not found or the manager is disabled, the original {{name}} token is preserved in the output.
• Non-recursive: Rendering only performs a single pass; it does not recursively resolve variables within resolved values.
• Performance: For high-frequency paths (like interceptors), use EnvironmentManager.tryRender(input) to avoid unnecessary overhead if the manager isn't loaded or the input doesn't contain {{.

// Example of variable rendering
// If 'api_host' is 'https://api.example.com' in the active environment:
String result = EnvironmentManager.tryRender('http://{{ api_host }}/v1') ?? '';
// result == 'http://https://api.example.com/v1'

// If 'missing_var' is not defined:
String result2 = EnvironmentManager.tryRender('{{ missing_var }}') ?? '';
// result2 == '{{ missing_var }}'

The EnvironmentManager is a singleton used to manage sets of environment variables. It supports a mandatory Global environment (which cannot be deleted) and multiple user-defined named environments (e.g., Dev, Staging, Prod).

Key behaviors:

• Global Environment: Always exists. Variables defined here act as fallbacks.
• Active Environment: Only one named environment can be active at a time via activeId. When an environment is active, its variables take precedence over Global variables.
• Variable Resolution: When resolving a variable name, the manager first looks in the active environment, then falls back to the global environment.
• Persistence: Configuration is stored in environments.json in the user's home directory.

// Accessing the singleton instance
final manager = await EnvironmentManager.instance;

// Setting the active environment
manager.setActive('some-env-id');

// Accessing the global environment
final globalEnv = manager.global;

// Accessing the currently active environment
final activeEnv = manager.active;