feat: add authentication-aware link validation (#34) #45
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implements comprehensive authentication detection and handling for external link validation.
This feature distinguishes between truly broken links and links that require authentication,
addressing false positives from Firebase Console, GitHub private repos, and other auth-protected URLs.
## Core Features
### Authentication Detection System
- **AuthDetector class**: Core authentication detection with configurable patterns and thresholds
- **Domain-based detection**: Recognizes auth-protected domains (Firebase, GitHub, AWS, etc.)
- **Status-based detection**: Identifies 401/403 responses as authentication requirements
- **Redirect-based detection**: Detects redirects to authentication pages (Google, Microsoft, etc.)
- **Pattern-based detection**: Recognizes content with staleness indicators
### Enhanced LinkValidator Integration
- **Seamless integration**: Authentication detection integrated into existing validation workflow
- **Credential support**: API keys and custom headers for authenticated validation
- **Smart request handling**: Uses GET requests when authentication is enabled for content analysis
- **Error differentiation**: Distinguishes auth-required from truly broken links
### CLI Integration
- **--enable-auth-detection**: Enable authentication-aware validation
- **--disallow-auth-required**: Treat auth-required links as broken (strict mode)
- **--auth-credentials**: JSON object with domain:credential mapping
- **--auth-headers**: JSON object with domain-specific headers
- **Enhanced output**: Shows auth-protected links with 🔒 indicator and detailed information
### Configuration & Flexibility
- **Configurable patterns**: Domain patterns and redirect patterns for different auth providers
- **Credential management**: Support for API keys, bearer tokens, and custom headers
- **Provider detection**: Automatic detection of auth providers (Google, GitHub, Microsoft, etc.)
- **Statistics tracking**: Separate counting of auth-required vs truly broken links
## Implementation Details
### New Files
- `src/utils/auth-detection.ts`: Core authentication detection utilities
- `src/utils/auth-detection.test.ts`: Comprehensive unit tests (35 test cases)
- `src/core/link-validator-auth.test.ts`: Integration tests (19 test cases)
- `src/commands/validate-auth.test.ts`: End-to-end tests (11 test cases)
### Enhanced Files
- `src/core/link-validator.ts`: Integrated authentication detection
- `src/commands/validate.ts`: Added auth options and statistics
- `src/types/config.ts`: Extended BrokenLink interface with auth info
- `src/cli.ts`: Added authentication CLI options with proper typing
### Key Patterns Supported
- Firebase Console: `console.firebase.google.com`
- GitHub Settings: `github.com/*/settings`
- Google Cloud Console: `console.cloud.google.com`
- AWS Console: `console.aws.amazon.com`
- Microsoft 365: `*.sharepoint.com`, `*.onedrive.com`
- Many others with wildcard support
## Example Usage
```bash
# Enable auth detection with default settings
markmv validate docs/ --check-external --enable-auth-detection
# Provide API credentials for validation
markmv validate docs/ --check-external --enable-auth-detection \
--auth-credentials '{"api.github.com":"Bearer token123"}'
# Use custom headers for specific domains
markmv validate docs/ --check-external --enable-auth-detection \
--auth-headers '{"api.example.com":{"X-API-Key":"key123"}}'
# Strict mode: treat auth-required as broken
markmv validate docs/ --check-external --enable-auth-detection --disallow-auth-required
```
## Test Coverage
- **Unit tests**: 35 tests for AuthDetector functionality
- **Integration tests**: 19 tests for LinkValidator integration
- **End-to-end tests**: 11 tests for complete validation pipeline
- **Total coverage**: 65 authentication-related test cases
Resolves #34
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Implements comprehensive authentication detection and handling for external link validation. This feature distinguishes between truly broken links and links that require authentication, addressing false positives from Firebase Console, GitHub private repos, and other auth-protected URLs.
Key Features
Implementation Highlights
anytypes)Example Usage
Output Enhancement
Domain Pattern Support
console.firebase.google.comgithub.com/*/settingsconsole.cloud.google.comconsole.aws.amazon.com*.sharepoint.com,*.onedrive.comTechnical Details
Resolves #34
Test Plan
anytypes used - full TypeScript type safety maintained