.env.example

# MailAccess Environment Configuration

# Application Environment
# Can be 'development' or 'production'
MAILACCESS_ENV=development

# Database Connection
# Leave empty to use SQLite (default: sqlite+aiosqlite:///~/.mailaccess/mailaccess.db).
# An ASYNC driver is REQUIRED — the app uses SQLAlchemy's async engine. Use the
# +asyncpg driver for Postgres (a plain postgresql:// URL will fail at startup).
# Example:
# DATABASE_URL=postgresql+asyncpg://user:password@db:5432/mailaccess
# DATABASE_URL=

# Backend Configuration
# The URL where the backend is accessible
BACKEND_URL=http://localhost:8000

# CORS Allowed Origins
# CORS_ORIGINS must be a JSON array - do not use a plain string
# Correct:   CORS_ORIGINS=["http://localhost:3000"]
# Wrong:     CORS_ORIGINS=http://localhost:3000
CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]

# Application debug mode (true/false)
DEBUG=false
# Log level: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

# Investigation Settings
# Maximum number of modules to run concurrently
MAX_CONCURRENT_MODULES=10
# Per-module timeout in seconds
MODULE_TIMEOUT_SECONDS=30
# MODULE_TIMEOUT_OVERRIDES must be a JSON object - do not use a plain string
# Correct:   MODULE_TIMEOUT_OVERRIDES={"username_platforms": 200}
# Wrong:     MODULE_TIMEOUT_OVERRIDES=username_platforms=200
MODULE_TIMEOUT_OVERRIDES={
  "username_platforms": 200,
  "account_discovery": 180,
  "breach_deep": 90
}

# Whether to enable investigation history persistence
ENABLE_HISTORY=true

# Investigate mode — overall wall-clock completion budget in seconds (Phase 1B).
# The whole investigation must finish within this time. When the budget is
# reached, in-flight modules are cut short and not-yet-started ones are skipped
# (both reported as budget_truncated) and the run COMPLETES with partial results
# instead of hanging or failing. Generous by default so the full module set
# completes on normal targets; it only bites pathological runs. The CLI
# `--budget` flag and the API `budget_seconds` field override per-run; <= 0 =
# unlimited.
INVESTIGATION_BUDGET_SECONDS=420
# Minimum budget a module needs left to be worth starting (else it is skipped
# as budget_truncated rather than run for a sliver of time).
INVESTIGATION_BUDGET_MIN_MODULE_SECONDS=2
# Optionally pin a fast primary module set for investigate (the fast-run
# workaround). JSON array of module names; when non-empty AND no --modules is
# given, the primary phase is restricted to these. Empty = full default set.
# Example: INVESTIGATION_FAST_MODULES=["hibp","gravatar_lookup","hudson_rock"]
INVESTIGATION_FAST_MODULES=[]

# 0.12.7 — Default JSON export on every harvest.
# When true, every `mailaccess harvest-emails` invocation writes a JSON
# result to ~/.mailaccess/results/{domain}_{timestamp}.json, plus a
# live log file.  Use --no-export on the CLI to opt out for a single
# run.
HARVEST_AUTO_EXPORT=true
# Per-domain rolling cap on the results directory.  When the cap is
# exceeded the oldest files for that domain are deleted on next run.
HARVEST_RESULTS_MAX_PER_DOMAIN=50
# Files older than this many days are deleted on next run.
HARVEST_RESULTS_MAX_AGE_DAYS=30

# Account discovery module: probes registration/reset endpoints for email-existence
# across 250+ services (native account-existence engine).
ENABLE_ACCOUNT_DISCOVERY=true  # 250+ email-checkable services

# Native username platform engine — the single username-url sweep over the local
# corpus (data/mailaccess_sites.json, 5,000+ platform definitions). No network
# fetch, no external tool install. Default true. Each run probes a bounded,
# rank/health-prioritized subset of the highest-signal platforms.
# Set to false only to disable for speed. Adds ~35-90s to investigation time.
ENABLE_USERNAME_PLATFORMS=true

# Username platform Wave 2 - slow/fragile platform sweep
# Additional regional and bot-protected platforms.
# Requires ENABLE_USERNAME_PLATFORMS=true. Adds ~90-150s additional.
ENABLE_USERNAME_WAVE2=false

# Maximum platform domains checked for infrastructure clustering
DOMAIN_CLUSTER_CAP=20

# Per-platform demotion override
# Replace {PLATFORM} with uppercase platform name,
# non-alphanum stripped. Example below:
# USERNAME_FORCE_GITHUBCOM=true

# Phase 6D.3 — opt-in community health sharing.
# Run `mailaccess platform-health --share` to post anonymized platform
# stats (hit rate, miss rate, inconclusive rate, avg latency, total probes,
# last_probed) to a public GitHub Gist. Strictly opt-in. Never runs
# automatically. Leave at false (or unset) — the --share flag is the only
# way this code path executes.
MAILACCESS_SHARE_HEALTH=false

# Enable domain infrastructure clustering
# Clusters platforms sharing registrar + /24 subnet
# Default: true. Cap controlled by DOMAIN_CLUSTER_CAP
enable_domain_cluster=true

# Username pivot: re-checks the username platform corpus using usernames recovered from primary findings.
ENABLE_USERNAME_PIVOT=true     # username cross-check

# Permutation discovery: auto-generates email variations and probes each.
ENABLE_PERMUTATION_DISCOVERY=true # email variations

# Email discovery: searches public results for other emails tied to recovered names.
ENABLE_EMAIL_DISCOVERY=false   # opt-in: needs SERPAPI_KEY

# Press intelligence: opt-in search of press release archives for contact phones.
ENABLE_PRESS_INTEL=false       # opt-in: no API key required

# Google-account intelligence: native, unauthenticated Gmail/Google account existence
# via MX/domain plus best-effort public profile (name, avatar). No credentials, on by default.
ENABLE_GOOGLE_ACCOUNT_INTEL=true
# Optional: a Google public web API key enables best-effort public-profile enrichment.
# Leave empty — the module still returns the stable MX/domain signal without it.
GOOGLE_INTEL_API_KEY=

# Phone intel: validate recovered phone numbers and probe WhatsApp/Telegram (post-primary).
ENABLE_PHONE_INTEL=true        # phone enrichment

# Messaging hints: best-effort Telegram username checks during primary gather.
ENABLE_MESSAGING_HINTS=true    # Telegram/WhatsApp hints

# PGP keyserver lookup: default-on public key UID name source, no API key required.
# MODULE: pgp_keyserver

# ORCID lookup: default-on public researcher identity source, no API key required.
# MODULE: orcid_lookup

# Hacker News lookup: default-on public profile/bio source, no API key required.
# MODULE: hackernews

# Deep breach mode: registration/reset probing against high-severity breached domains.
ENABLE_BREACH_DEEP=false       # opt-in: slow 90s probe
BREACH_DEEP_LIMIT=100
BREACH_DEEP_FULL=false

# Breach aggregation (Phase 5) — four sources, run on confirmed emails.
# Scylla.so: free, no key required
ENABLE_SCYLLA=true
# HIBP pastes (requires existing HIBP_API_KEY)
ENABLE_HIBP_PASTES=true
# Dehashed: paid, dehashed.com
DEHASHED_API_KEY=
# Dehashed account login email (not target email)
DEHASHED_ACCOUNT_EMAIL=your@email.com
# Snusbase: paid, snusbase.com
SNUSBASE_API_KEY=

# Optional proxy for all requests (e.g. Tor or HTTP proxy)
# Example: socks5://127.0.0.1:9050  (Tor) or http://user:pass@proxy:port
PROXY_URL=
# Set to true to activate the proxy. Proxy is ignored when false.
PROXY_ENABLED=false

# Per-domain rate limiting
# Set to false to disable all rate limiting (not recommended in production)
RATE_LIMIT_ENABLED=true
# Default minimum delay between requests to the same domain (milliseconds)
REQUEST_DELAY_MS=1000
# Per-domain overrides as a JSON object (values in milliseconds)
# Example: RATE_LIMIT_OVERRIDES={"api.github.com": 500, "api.xposedornot.com": 1000, "haveibeenpwned.com": 1500}
RATE_LIMIT_OVERRIDES={}
# Legacy per-domain delays in seconds (JSON object): RATE_LIMIT_DELAYS={"haveibeenpwned.com": 1.5}
RATE_LIMIT_DELAYS={}

# Integrations (Webhooks)
SLACK_WEBHOOK_URL=
DISCORD_WEBHOOK_URL=
INTEGRATION_WEBHOOK_URL=
INTEGRATION_WEBHOOK_SECRET=

# API Keys (all optional, features will be disabled if key is missing)
# MAILACCESS_API_KEY restricts access to the REST API if set
MAILACCESS_API_KEY=

# 0.17.0 — hosted paid lead-enrichment tier (Stream 2).
# MAILACCESS_PRO_KEY is a CALLER's paid entitlement, presented to /v1/enrich.
MAILACCESS_PRO_KEY=
# Server-side: the corpus lead-engine origin. Only this backend queries the
# engine, over a private mesh; set this to the deployment's private endpoint.
MAILACCESS_PRO_BASE_URL=
# Shared secret mirrored onto the engine — gates /api/internal/search.
MAILACCESS_PRO_ENGINE_SECRET=
# Shared secret for the website-to-backend provisioning bridge. This endpoint is
# private/mesh-only and fails closed when the secret is unset.
MAILACCESS_PRO_INTERNAL_SECRET=
# The Phase-6 public-launch gate. While false the paid tier is unavailable
# regardless of key validity (a legal/owner decision, not an engineering one).
MAILACCESS_PRO_LAWFUL_BASIS_ESTABLISHED=false

# Have I Been Pwned API Key for breach data (hibp module)
HIBP_API_KEY=

# XposedOrNot uses public breach endpoints and does not require an API key.

# LeakCheck uses public breach endpoints and does not require an API key.


# BreachDirectory API Key (RapidAPI — breachdirectory module)
# Free tier: https://rapidapi.com/rohan-patra/api/breachdirectory
BREACHDIRECTORY_API_KEY=

# SerpAPI Key for Google dork queries (google_dork and email_discovery modules)
SERPAPI_KEY=

# GitHub personal access token (optional)
# Required for github_commits commit search
# Without it, only user profile search runs
# Get at: github.com/settings/tokens
GITHUB_TOKEN=

# Shodan API Key for host intelligence (shodan module and domain_intel)
SHODAN_API_KEY=

# EmailRep API Key for email reputation checking (emailrep module, optional - raises rate limits)
EMAILREP_API_KEY=

# Hunter.io API Key for email deliverability checks (hunter_io module)
HUNTER_IO_API_KEY=

# Google Custom Search (optional, 100/day free)
# Significantly improves search dork yield
# Get at: programableseach.google.com → New Search Engine
GOOGLE_CSE_API_KEY=
GOOGLE_CSE_CX=

# Supported search API for harvest dorking: auto, brave, or legacy_html.
# auto uses Brave when configured and otherwise records DDG/Bing as best-effort.
SEARCH_PROVIDER=auto
BRAVE_SEARCH_API_KEY=
ENABLE_PUBLIC_SURFACE_SWEEPER=true
PUBLIC_SURFACE_MAX_URLS=12
ENABLE_PUBLIC_FORGE=true
PUBLIC_FORGE_MAX_PROJECTS=5
PUBLIC_FORGE_MAX_COMMITS=10
ENABLE_PACKAGE_ECOSYSTEMS=true
PACKAGE_ECOSYSTEMS_MAX_PACKAGES=5
ENABLE_SUBDOMAIN_SURFACE=true
SUBDOMAIN_SURFACE_MAX_HOSTS=8
ENABLE_SYNDICATION_FEED_SWEEPER=true
ENABLE_HARVEST_HISTORY_CACHE=true
HARVEST_CACHE_ENABLED=true
HARVEST_CACHE_TTL_SECONDS=3600

# --- Shared Corpus Flywheel (Phase 6) ---------------------------------------
# Private-by-default. The distribution/contribution machinery is INERT: it never
# publishes without the master switch on, a configured transport, and explicit
# per-batch approval. 6A/6C/6F are local-only and safe to leave on.
# 6A — confidence decay (down-weights + flags aging corpus rows at serve time).
ENABLE_CORPUS_DECAY=true
CORPUS_DECAY_ANNUAL_ROT=0.28
CORPUS_DECAY_MIN_FACTOR=0.3
CORPUS_DECAY_STALE_AFTER_DAYS=180
# 6C — corpus-derived Bayesian pattern priors fed into pattern inference.
ENABLE_CORPUS_PATTERN_PRIORS=true
# 6F — change intelligence (new-hire / departure / stale signals from diffs).
ENABLE_CHANGE_INTELLIGENCE=true
# 6D/6E — federated distribution + opt-in contribution. OFF (inert) by default;
# activated only after the infra decision and with explicit approval.
ENABLE_CORPUS_DISTRIBUTION=false
ENABLE_CORPUS_CONTRIBUTION=false
CORPUS_DISTRIBUTION_SHARDS=256
# CORPUS_SIGNING_KEY=            # local key generated if unset
CORPUS_CONTRIBUTION_MAX_PER_BATCH=500
CORPUS_CONTRIBUTION_MAX_PER_WINDOW=5
CORPUS_CONTRIBUTION_WINDOW_SECONDS=3600
ENABLE_YIELD_PREDICTION=true
YIELD_PREDICTION_TAIL_SECONDS=15
ENABLE_KEYBASE_LOOKUP=true
ENABLE_HACKERNEWS_LOOKUP=true

# Companies House API (UK company officer data)
# Free forever, no credit card required
# Get at: developer.company-information.service.gov.uk
COMPANIES_HOUSE_API_KEY=

# Show Defender's Brief in CLI output (default: true)
# Set to false to suppress for all investigations
SHOW_DEFENDERS_BRIEF=true

# ═══════════════════════════════════════════════
# DOMAIN EMAIL HARVESTING (mailaccess harvest-emails)
# ═══════════════════════════════════════════════

# Common Crawl source (primary free source)
ENABLE_COMMONCRAWL_EMAIL=true
CC_MAX_RECORDS=100
CC_FETCH_CONCURRENCY=10
# Phase 3 multi-collection sweep.  The module sweeps up to
# CC_MAX_COLLECTIONS newest Common Crawl collections; each collection's
# CDX query is capped at CC_MAX_RECORDS_PER_COLL rows.
CC_MAX_COLLECTIONS=6
CC_MAX_RECORDS_PER_COLLECTION=250

# Wayback Machine domain-mode harvest (Phase 3).
# Runs alongside Common Crawl in Phase 1 of the harvest orchestrator.
ENABLE_WAYBACK_HARVEST=true
# Post-scoring cap on URLs fetched per harvest (top-signal first).
WAYBACK_MAX_URLS=100

# Syndication feed sweep (RSS / Atom author extraction)
ENABLE_SYNDICATION_FEED_SWEEPER=false

# Search engine dorking (DDG + Bing)
ENABLE_EMAIL_SEARCH_DORK=true
DORK_MAX_QUERIES_PER_ENGINE=5
DORK_LITE_MODE=false

# Code repository + certificate transparency
ENABLE_CODE_AND_CERT_EMAIL=true
GITHUB_EMAIL_MAX_RESULTS=30

# Employee name discovery (feeds pattern generation)
ENABLE_EMPLOYEE_NAME_DISCOVERY=true
EMPLOYEE_NAME_MAX_COMPANY_PAGES=5
# ML name classifier (ask/on/off). Requires:
#   pip install mailaccess[ml]
#   python -m spacy download en_core_web_md
ML_NAME_CLASSIFIER=off

# SMTP verification runs by default. Use --no-verify for a single-run opt-out.
SMTP_VERIFY_DEFAULT=true
SMTP_VERIFY_MAX_PROBES=10
SMTP_VERIFY_TIMEOUT=10
SMTP_GREYLIST_RETRY_DELAY=30
# Legacy aliases retained for compatibility.
ENABLE_SMTP_VERIFICATION=true
SMTP_MAX_PROBES_PER_DOMAIN=10
SMTP_PROBE_DELAY_SECONDS=2.5

# Reactive public-web email search for qualified discovered names.
PERSONA_PIVOT_ENABLED=true
PERSONA_PIVOT_MAX_NAMES=10
PERSONA_PIVOT_MAX_QUERIES_PER_NAME=3

# Automatic validation of LOW-confidence on-domain personal emails during
# every domain harvest. Enabled by default; set false to disable the validator.
ENABLE_LOW_EMAIL_VALIDATION=true
# Keyless XposedOrNot passive breach corroboration.
XPOSED_OR_NOT_ENABLED=true
# Maximum number of LOW emails the automatic validator will process per harvest.
HARVEST_VALIDATION_MAX_PER_RUN=25
# Google Workspace account-existence signal. Disable if Google changes the
# undocumented recovery endpoint behavior.
GOOGLE_WORKSPACE_VERIFIER_ENABLED=true
GOOGLE_VERIFIER_TIMEOUT=8
GRAVATAR_VERIFICATION_ENABLED=true

# Pattern generation confidence thresholds
# Names below medium threshold get no patterns
PATTERN_HIGH_CONFIDENCE_THRESHOLD=0.75
PATTERN_MEDIUM_CONFIDENCE_THRESHOLD=0.50

# Package registry sources
ENABLE_NPM_EMAIL=true
ENABLE_PYPI_EMAIL=true

# PGP keyserver source
ENABLE_PGP_DOMAIN_EMAIL=true
# ScrapingAnt - Web Scraping API (billed in credits, Enthusiast plan)
SCRAPINGANT_API_KEY=
# ScrapingAnt - Residential Proxies (billed in GB, Micro plan)
# Dashboard issues SEPARATE username/password (NOT the API key).
SCRAPINGANT_PROXY_RESIDENTIAL_USERNAME=
SCRAPINGANT_PROXY_RESIDENTIAL_PASSWORD=
# ScrapingAnt - Datacenter Proxies (billed in GB, separate dashboard creds)
SCRAPINGANT_PROXY_DATACENTER_USERNAME=
SCRAPINGANT_PROXY_DATACENTER_PASSWORD=
# Transport selector: rest_api | residential_proxy | datacenter_proxy
SCRAPINGANT_TRANSPORT=rest_api

# 0.11.1 Phase 1 — Stealth HTTP client (harvest mode only).
# Pacing profile for stealth harvest requests.  One of:
#   t0 = T0 Ghost    (8s mean, 4-20s)  — max stealth, slow
#   t1 = T1 Stealth  (4s mean, 2-10s)  — high stealth
#   t2 = T2 Balanced (2s mean, .8-6s)  — default
#   t3 = T3 Normal   (1s mean, .4-3s)  — normal cadence
#   t4 = T4 Fast     (.3s mean, .1-1s) — minimal stealth
#   t5 = T5 Insane   (0s, no pacing)   — tests / benchmarks only
HARVEST_TIMING_PROFILE=t2
# curl-cffi impersonation target.  Currently only "chrome120" is exercised.
HARVEST_IMPERSONATE_BROWSER=chrome120

# 0.11.1 Phase 2 — Site Intelligence Rebuild.
# Enable low-confidence body-text name extraction in the company
# page harvester.  Default false — opt in via the ``--aggressive``
# CLI flag or set this to true.  Forces more permissive thresholds
# across the harvest pipeline.
HARVEST_AGGRESSIVE=false
# Cap on probe-fetched URLs after merging sitemap / homepage /
# robots-discover candidates.  Spec default is 15.
SITE_DISCOVERY_MAX_CANDIDATES=15