Git Commit

Git commit

Creates git commits following Conventional Commits format.

Recent project commits

!git log --oneline -5 2>/dev/null

Quick start

# 1. Stage changes
git add <files>

# 2. Create commit
git commit -m "type(scope): subject"

Project conventions

• Scope is required (kebab-case): validation, auth, cookie-service, api
• Additional type beyond standard CC: security (vulnerability fixes or hardening)
• HEREDOC for multi-line commits:

git commit -m "$(cat <<'EOF'
feat(validation): add URLValidator with domain whitelist

Implement URLValidator class supporting:
- Domain whitelist enforcement
- Dangerous scheme blocking

Addresses Requirement 31
Part of Task 5.1
EOF
)"

Important rules

• ALWAYS check CLAUDE.md conventions first - use project format if it differs
• ALWAYS include scope in parentheses
• ALWAYS use present tense imperative verb for the subject
• NEVER end subject with a period
• NEVER exceed 50 chars in the subject line
• NEVER use generic messages ("update code", "fix bug", "changes")
• Group related changes into a single focused commit

References

• references/commit_examples.md - Extended examples by type, good/bad comparisons

Commit Examples by Type

Extended examples for each commit type with body content.

feat - New Features

feat(validation): add URLValidator with domain whitelist

Implement URLValidator class supporting:
- Domain whitelist enforcement (youtube.com, youtu.be, m.youtube.com)
- Dangerous scheme blocking (javascript, data, file)
- URL parsing with embedded credentials handling
- Port number validation (1-65535)

Addresses Requirement 31: Input validation
Part of Task 5.1: Input Validation Utilities

feat(api): add video metadata endpoint

New GET /api/v1/videos/{id}/metadata endpoint:
- Returns title, duration, formats, thumbnails
- Supports format filtering via query params
- Implements caching with 5-minute TTL

Part of Task 6.2: API Endpoints

fix - Bug Fixes

fix(auth): use hmac.compare_digest for secure key comparison

Replace direct string equality with hmac.compare_digest to prevent
timing attacks on API key validation. Ensures constant-time comparison
regardless of key length or content.

Addresses security best practice for sensitive data comparison

fix(download): handle network timeout during video fetch

Add retry logic with exponential backoff for network failures:
- Max 3 attempts with delays [2, 4, 8] seconds
- Classify retriable errors (5xx, timeout, connection)
- Log each retry attempt with remaining count

Fixes issue where downloads would fail silently on flaky connections

refactor - Code Improvements

refactor(template): consolidate filename sanitization logic

Extract common sanitization patterns into helper methods:
- Path traversal prevention (.., /, absolute paths)
- Special character removal (control chars, null bytes)
- Windows reserved name handling (CON, PRN, LPT1-9, etc)

Improves code maintainability and reduces duplication

refactor(providers): extract common yt-dlp options builder

Move duplicated option building from get_info/download to
_build_base_options helper. Reduces code duplication and ensures
consistent option handling across all provider methods.

No behavior change, pure refactoring

test - Test Changes

test(security): add 102 path traversal prevention tests

Comprehensive test coverage for TemplateProcessor including:
- Basic path traversal attempts (.., /)
- URL-encoded variants (%2e%2e, %2f)
- Unicode/UTF-8 bypass attempts
- Windows edge cases (backslashes, drive letters)

Part of Task 5.4: Security Test Suite

test(validation): add parametrized URL validation tests

Add 25 test cases covering:
- Valid YouTube URL formats (watch, shorts, embed, youtu.be)
- Invalid domains (vimeo, dailymotion)
- Malformed URLs (no scheme, wrong port)
- Edge cases (trailing slashes, query params)

Coverage for URLValidator: 98%

perf - Performance

perf(cache): implement LRU eviction for metadata cache

Replace dict-based cache with LRU implementation:
- Max 1000 entries with automatic eviction
- 40% memory reduction under high load
- Sub-millisecond lookup times maintained

Addresses memory growth issue in long-running instances

security - Security Fixes

security(cookie): validate cookie file integrity before use

Add SHA256 checksum verification for cookie files:
- Compute hash on first load, store in memory
- Verify hash before each use
- Reject modified files with clear error message

Prevents use of tampered cookie files
Addresses Requirement 33: Security validation

ci - CI/CD Changes

ci(github): add security scanning to PR workflow

Enable Bandit security scanner in GitHub Actions:
- Run on all Python files
- Fail on HIGH/CRITICAL findings
- Cache virtualenv for faster runs

Part of Task 15.3: Basic security validation

docs - Documentation

docs(api): add OpenAPI description for download endpoint

Document /api/v1/download endpoint:
- Request body schema with format options
- Response codes (200, 400, 401, 404, 500)
- Example requests and responses

Improves API documentation for consumers

chore - Maintenance

chore(deps): update yt-dlp to 2024.12.06

Update yt-dlp from 2024.11.15 to 2024.12.06:
- Fixes YouTube throttling detection
- Adds support for new Instagram format
- Improves error messages for geo-blocked content

No breaking changes expected

style - Formatting

style(providers): apply black formatting to youtube.py

Apply black formatter with 88 char line length.
No functional changes, formatting only.

Merge Commit Examples

Feature Branch to Develop

Merge pull request #5 from fvadicamo/feature/input-validation-security

feat(security): implement input validation and security (Task 5)

Merges comprehensive security implementation (Task 5) into develop:
- Input validation utilities (URLValidator, FormatValidator, ParameterValidator)
- Secure template processor with path traversal prevention
- API key authentication middleware with multi-key support
- 473 tests with 93% coverage

Task 5.1: Input Validation Utilities
- URLValidator: Domain whitelist (youtube.com, youtu.be), dangerous scheme blocking
- FormatValidator: yt-dlp format ID validation with regex and selectors
- ParameterValidator: Audio quality/format and language code validation

Task 5.2: Template Processor
- Path traversal prevention (.., /, absolute paths, URL encoding)
- Filename sanitization (illegal chars, control chars, null bytes)
- Windows reserved names handling (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
- Collision handling with numeric suffix, max length 200 chars

Task 5.3: API Key Authentication
- APIKeyAuth class with multi-key support
- Excluded paths for health/doc endpoints
- Secure hashing for logging (SHA256 first 8 chars)
- FastAPI dependency injection integration

Task 5.4: Security Tests
- 102 path traversal prevention tests with edge cases
- URL validation tests with malicious inputs
- API key authentication and credential tests
- Sensitive data redaction verification

Requirements Covered:
- Req 7: Output template processing with security
- Req 9: API key authentication
- Req 31: Input validation
- Req 33: Security (secure comparison, log redaction)

Test Coverage:
- All 473 tests passing
- Coverage: 93% (exceeds 80% minimum)
- Pre-commit checks: all passing

Develop to Main (Release)

Merge pull request #10 from fvadicamo/develop

release: v0.1.0 - MVP with YouTube provider

First stable release with core functionality:
- YouTube video info, formats, download, audio extraction
- Cookie-based authentication for age-restricted content
- API key authentication
- Input validation and security hardening
- 500+ tests with 92% coverage

Breaking Changes: None (initial release)

Features:
- GET /api/v1/info - Video metadata
- GET /api/v1/formats - Available formats
- POST /api/v1/download - Video/audio download
- Cookie file support for authenticated requests

Documentation:
- API documentation at /docs (Swagger UI)
- OpenAPI spec at /openapi.json

Good vs Bad Examples

Good:

feat(validation): add URLValidator with domain whitelist
fix(auth): use hmac.compare_digest for secure key comparison
refactor(template): consolidate filename sanitization logic
test(security): add 102 path traversal prevention tests

Bad:

update validation code           # no type, no scope, vague
feat: add stuff                  # missing scope, too vague
fix(auth): fix bug               # circular, not specific
chore: make changes              # missing scope, vague
feat(security): improve things.  # has period, vague

Commits with Trailers

Single Issue

fix(validation): prevent XSS in user input

Escape HTML entities before rendering.

Fixes #78

Multiple Issues + Co-author

fix(auth): resolve session and token issues

- Fix session expiry not triggering logout
- Fix token refresh race condition

Fixes #101
Fixes #103
Co-authored-by: Bob <bob@example.com>

Breaking Changes

With ! Notation

feat(api)!: migrate to v2 endpoints

BREAKING CHANGE: /api/v1/* endpoints removed. Update base URL to /api/v2/.

Config Breaking Change

chore(config)!: rename environment variables

BREAKING CHANGE: DATABASE_URL -> APP_DATABASE_URL, API_KEY -> APP_API_KEY