feat(login-engine): add interactive CLI entrypoint, dynamic SPA hydration polling, and robust auth verification

[Edge-Explorer]

Summary by CodeRabbit

• New Features
  • Added a command-line workflow for logging in to a website with a target URL and optional credentials.
  • Added support for loading credentials from environment variables or a .env file when credentials aren’t supplied directly.
• Improvements
  • Login flows now wait for page changes and check for login fields more consistently.
  • Authentication results more accurately reflect rejected or incomplete logins, and saved sessions can be bypassed when entering credentials explicitly.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: Edge-Explorer/Tracepass/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: d6afb35e-edc1-4ce5-bf53-59b3f8af7c49

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key: "path_filters"

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🤖 PR Detailed Review & Summary by Gemini Code Intelligence

1. Executive Summary (In Plain English)

This Pull Request introduces significant enhancements to the Tracepass autonomous login engine, making it more user-friendly, robust, and adaptable to modern web applications. The core changes include a new interactive command-line interface (CLI) for direct user interaction, advanced mechanisms for handling Single Page Applications (SPAs) through dynamic DOM hydration polling and post-submission navigation detection, and a more sophisticated authentication verification process. Additionally, credential management is improved by supporting .env files and dedicated environment variables, streamlining the process of providing login details. These updates collectively make Tracepass a more powerful and versatile tool for automated login.

2. Motivation & Root Cause Analysis

The previous iteration of the Tracepass login engine faced several challenges that limited its effectiveness and ease of use:

1. Lack of Direct User Interface: The absence of a command-line interface meant users had to modify code to specify target URLs and credentials, hindering quick testing and general usability.
2. Inadequate SPA Handling: Modern web applications, particularly SPAs built with frameworks like React or Vue, dynamically load content after the initial page render. The engine struggled to reliably detect login fields or post-login navigation on such sites, leading to failed login attempts.
3. Insufficient Authentication Verification: The existing AuthVerifier could sometimes misinterpret login states, especially when error messages were subtle or when authentication tokens were present but held empty or invalid values, leading to false positives or negatives.
4. Limited Credential Loading Flexibility: Credential management was restricted to in-memory injection or OS keyring, lacking support for common developer practices like .env files or dedicated environment variables for easy configuration.
5. Session Cache Interference: When users intended to test specific credentials, the engine's session cache could prematurely restore a previous session, bypassing the explicit credentials provided and leading to confusion.
6. Modal Trigger Misidentification: The FieldDetector occasionally misidentified standard navigation hyperlinks as modal triggers, potentially leading to incorrect interaction attempts during form analysis.

3. Step-by-Step Technical Solution

1. Interactive CLI Entrypoint (main.py):
   • The main.py file was refactored to include an argparse-based command-line interface, allowing users to specify the target url, username, and password directly.
   • If arguments are omitted, interactive prompts using input() and getpass.getpass() guide the user to provide necessary details securely.
   • A new asynchronous function, run_tracepass, orchestrates the LoginEngine and StealthyFetcher, providing structured output on the login attempt's success or failure.
   • Crucially, if credentials are explicitly provided by the user (via CLI or interactive prompt), the skip_session_cache=True flag is passed to LoginEngine.authenticate() to ensure these credentials are always tested.
2. Dynamic SPA Hydration Polling (core/login_engine.py):
   • Stage 3 (DOM Flow Analysis) within LoginEngine.authenticate() was significantly enhanced with a robust polling loop, designed to wait for dynamic content hydration in SPAs.
   • This loop, active for up to 15 seconds, repeatedly attempts page.wait_for_selector for common login input fields and then calls field_detector.detect_fields on the current DOM content.
   • The loop breaks early upon successful detection of login fields, ensuring the engine proceeds only when the necessary elements are rendered and interactive.
3. Enhanced Post-Submission Waiting for SPAs (core/handlers/single_step.py):
   • Before submitting the login form, the current page.url is captured as pre_submit_url.
   • After submission, a new polling mechanism (up to 10 seconds, with 0.5-second intervals) actively checks if the page's URL has changed. This is a strong indicator of successful navigation away from the login page, typical for SPAs.
   • If navigation is detected, the handler waits for domcontentloaded on the new page. If no navigation occurs, it falls back to waiting for networkidle and a final asyncio.sleep(2) to handle inline error messages or very slow SPA transitions.
4. Robust Authentication Verification (core/auth_verifier.py):
   • The AuthVerifier now includes an expanded set of CSS selectors for detecting visible error banners, specifically targeting common SPA patterns like [class*='errorMessage'], [class*='error-'], and [class*='inputError'].
   • The logic for detecting a visible password input after submission was clarified to explicitly indicate a rejected or incomplete login.
   • The check for authentication tokens in local_storage was improved to filter out empty or placeholder values (e.g., "", {}, null), ensuring that only genuinely populated tokens contribute to a positive authentication signal.
   • A clear signal evaluation order was added to the docstring for better understanding of the verification process.
5. Flexible Credential Management (core/credential_manager.py):
   • A new static method, _load_env_file(), was introduced to parse key-value pairs from a local .env file into os.environ if the file exists.
   • The get_credentials() method now calls _load_env_file() at the beginning of its credential resolution process.
   • Support for TRACEPASS_USERNAME and TRACEPASS_PASSWORD environment variables was added as a fallback, providing more versatile credential loading options.
6. Refined Modal Trigger Detection (core/field_detector.py):
   • The detect_modal_trigger() method was modified to explicitly ignore <a> tags that function as standard navigation hyperlinks (i.e., their href attribute does not start with # or javascript:), preventing false positives when identifying elements that open modals.
7. Live Experiment Tests (experiments/test_live_discord.py, experiments/test_live_engine.py):
   • Two new experiment files were added to demonstrate and validate the enhanced login engine. test_live_discord.py targets a real-world SPA (Discord) with interactive credential input, while test_live_engine.py uses a simpler test site (the-internet.herokuapp.com) with hardcoded credentials, serving as robust integration tests and usage examples.

4. File-by-File Breakdown & Key Implementation Details

File	Action	Purpose & Key Implementation Details
core/auth_verifier.py	Modified	Error Detection: Expanded CSS selectors for error banners to include common SPA patterns like [class*='errorMessage'], [class*='error-'], and [class*='inputError'], improving the detection of login failures. Password Input Check: Clarified that a visible password input after submission indicates a rejected or incomplete login, returning False. Auth Storage Validation: Enhanced has_auth_storage to filter out empty or placeholder values ("", {}, null, etc.) for auth tokens, ensuring a more reliable positive authentication signal.
core/credential_manager.py	Modified	.env File Support: Added a static method _load_env_file() to parse key-value pairs from a local .env file into os.environ, making credential loading more flexible. Environment Variable Fallback: get_credentials() now checks for TRACEPASS_USERNAME and TRACEPASS_PASSWORD environment variables as a fallback, providing additional options for credential configuration.
core/field_detector.py	Modified	Modal Trigger Refinement: Modified detect_modal_trigger() to explicitly ignore <a> tags that are standard navigation hyperlinks (i.e., href not starting with # or javascript:), preventing misidentification of non-modal elements.
core/handlers/single_step.py	Modified	SPA Navigation Detection: Implemented a post-submission polling loop (up to 10 seconds) that checks for URL changes, indicating successful navigation away from the login page, crucial for SPAs. Load State Management: If navigation occurs, it waits for domcontentloaded; otherwise, it falls back to networkidle and a final asyncio.sleep(2) to handle inline errors or slow loads.
core/login_engine.py	Modified	Session Cache Control: Added skip_session_cache parameter to authenticate() to allow callers to bypass cached sessions, ensuring explicitly provided credentials are always attempted. Dynamic SPA Polling: Replaced static wait_for_selector with a robust 15-second polling loop in Stage 3, repeatedly checking for visible login fields to accommodate dynamic DOM hydration in SPAs.
experiments/test_live_discord.py	Added	Discord Live Test: Introduces a new experiment script to test the LoginEngine against Discord's login page, demonstrating its enhanced SPA handling capabilities and interactive credential input. It prompts the user for credentials and logs the login outcome.
experiments/test_live_engine.py	Added	Generic Live Test: Adds a basic live test for LoginEngine using a simple, known login page (the-internet.herokuapp.com). This serves as a quick integration test and example for the core login functionality with hardcoded credentials.
main.py	Modified	CLI Entrypoint: Transformed into an interactive command-line tool using argparse for URL and credential input, with getpass for secure password entry. Orchestration: The run_tracepass async function now orchestrates the LoginEngine and StealthyFetcher, providing a user-friendly interface for autonomous login attempts and displaying detailed results.

5. Architecture, Reliability & Security Considerations

• Architecture & Maintainability: The changes are well-integrated into the existing modular design, enhancing specific components without introducing tight coupling. The new CLI (main.py) provides a clean separation of concerns, acting as a user-facing orchestrator. The polling mechanisms for SPA handling are encapsulated within LoginEngine and SingleStepHandler, improving robustness and maintainability for dynamic web environments. The addition of live experiment tests significantly improves the testability and provides clear usage examples.
• Security & Secrets: The use of getpass.getpass() in main.py for interactive password input is a strong security practice, preventing sensitive data from being displayed on the console. The .env file loading and environment variable fallbacks in CredentialManager offer convenient, secure ways to manage credentials for local development and testing, provided .env files are excluded from version control and environment variables are managed securely in production. The enhanced AuthVerifier logic for local storage tokens now explicitly filters out empty/placeholder values, reducing the risk of false positives and potential security misinterpretations.
• Performance: The introduction of polling loops (up to 15 seconds in LoginEngine and up to 10 seconds in SingleStepHandler) adds a potential delay to the login process, especially for sites that hydrate quickly or fail immediately. This is a necessary trade-off for robustness in dynamic SPA environments, with reasonable polling intervals (1s and 0.5s) to balance responsiveness and resource usage. The _load_env_file() method's overhead is negligible given its typical infrequent usage.

6. Risk Assessment & Edge Cases

• Overall Risk Level: 🟡 Medium
  The changes are substantial, affecting core components and introducing new interaction patterns. While designed for robustness, the inherent complexity of autonomous interaction with diverse web applications introduces some risk. The new polling mechanisms, though beneficial, could lead to unexpected delays or timeouts on highly unusual or extremely slow-loading sites.
• Potential Edge Cases / Side Effects:
  • Extremely Slow SPAs: While improved, exceptionally slow-loading SPAs might still exceed the polling timeouts before fields are detected or navigation occurs, potentially leading to false negatives.
  • Complex Multi-Step Flows: The current enhancements primarily focus on single-step login flows. Multi-step authentication (e.g., OAuth, CAPTCHA pages, MFA) would still require specialized handlers beyond the scope of this PR.
  • Aggressive Anti-Bot Measures: Some websites might detect the polling behavior or rapid DOM content checks as bot-like activity, potentially triggering CAPTCHAs, rate limits, or outright blocks.
  • Malformed .env Files: Although _load_env_file() includes error handling, a severely malformed .env file could still cause unexpected behavior or prevent credentials from loading.
  • False Positive Modal Triggers: Despite improvements, field_detector.py might still occasionally misidentify a non-login-related element as a modal trigger on highly unconventional page layouts.
  • Credential Precedence Confusion: While the credential loading order is defined, users might be confused if a lower-priority source (e.g., environment variables) overrides an expected higher-priority one (e.g., OS keyring) when not explicitly providing credentials. The skip_session_cache flag helps mitigate this for explicit user input.

7. Reviewer & Testing Verification Checklist

• Verify the CLI (main.py) by running python main.py without arguments and interactively providing a target URL, username, and password. Confirm the login attempt proceeds and results are displayed.
• Test the CLI with command-line arguments: python main.py https://the-internet.herokuapp.com/login -u tomsmith -p SuperSecretPassword! and confirm successful login.
• Create a .env file in the project root with TRACEPASS_USERNAME=testuser and TRACEPASS_PASSWORD=testpass. Run python main.py https://example.com/login (or a test site) without -u/-p flags and verify that CredentialManager picks up these environment variables.
• Execute python experiments/test_live_discord.py and manually provide Discord credentials. Verify that the engine correctly navigates the Discord SPA login flow and reports success/failure.
• Execute python experiments/test_live_engine.py and confirm successful autonomous login to https://the-internet.herokuapp.com/login using the hardcoded credentials.
• Manually review core/auth_verifier.py to confirm the expanded error selectors and the logic for validating authentication tokens in local storage are robust and accurate.
• Manually review core/login_engine.py and core/handlers/single_step.py to understand the new polling and navigation detection logic for SPAs, ensuring the timeouts and conditions are appropriate.
• Verify that when credentials are explicitly provided via the CLI or interactive prompt, the skip_session_cache=True flag is correctly passed to LoginEngine.authenticate(), ensuring the provided credentials are always attempted.
• Confirm that core/field_detector.py correctly ignores standard navigation <a> tags when detecting modal triggers, preventing false positives.

[abhirajsingh1234]

@Edge-Explorer Fantastic the Login Tracepassing is done perfectly