MailHunter 4.0

MailHunter 4.0 is a React/Vite web investigation workspace plus a separate native Kotlin/Jetpack Compose Android client. Both clients use the hardened Vercel/Firebase/Gmail Watch backend. The old Capacitor project is retained only for migration reference and is no longer the production Android target.

Version

• Web/package: 4.0.0
• Native Android versionName: 4.0.0
• Native Android versionCode: 40
• Android application ID: com.cybroatrix.mailhunter

Local verification

Requirements: Node.js 22 LTS and npm.

npm install
npm run verify

npm run verify runs both TypeScript targets, ESLint, adversarial regression tests, native-source architecture checks, a production Vite build, and legal-page checks. Run npm audit separately to inspect the dependency report.

Configure the backend

1. Copy .env.example to .env.production.
2. Fill the public VITE_* values and the server-only Firebase, Gmail OAuth/Pub/Sub, encryption, cron, rate-limit, and optional provider values.
3. Never commit .env.production, a service-account key, an Android keystore, or google-services.json.
4. Deploy to Vercel and configure the authenticated Pub/Sub push endpoint as described in CLOSED-APP-GMAIL-SETUP.md.
5. Deploy firestore.rules before enabling saved investigations or push-device registration.

Build the native Android app on Windows

Requirements: Android Studio with Android SDK 36, JDK 17, Node.js 22 LTS, and the Android OAuth/Firebase configuration for com.cybroatrix.mailhunter.

1. In Firebase, register the Android app and add the SHA-1/SHA-256 fingerprints for the key used to sign it.
2. Download google-services.json to native-android/app/google-services.json.
3. Copy native-android/local.properties.example to native-android/local.properties, set your Windows SDK path, HTTPS backend URL, and Web OAuth client ID.
4. Put the matching Web OAuth client ID/secret in the deployed server as GOOGLE_WEB_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET, set GMAIL_TOKEN_ENCRYPTION_KEY, and publish the OAuth consent screen to Production.
5. In PowerShell:

npm install
npm run verify
cd native-android
.\gradlew.bat testDebugUnitTest
.\gradlew.bat assembleDebug

The debug APK is created at native-android/app/build/outputs/apk/debug/app-debug.apk. The build intentionally fails if the Firebase file, backend URL, Web OAuth client ID, or package mapping is missing. See NATIVE-ANDROID-SETUP.md for signing fingerprints and Play App Signing.

Important interpretation limits

• HASH_RECORDED means MailHunter computed a baseline SHA-256. It does not mean the evidence was independently authenticated.
• Uploaded authentication headers are untrusted observations. Only a known acquisition channel/trusted receiver or independent DKIM/DMARC verification can affect the canonical authentication assessment.
• A risk score of zero means no completed check raised a signal; it is not proof an email is safe.
• IP geolocation describes network/mail infrastructure, not a person's exact physical location.
• The evidence ledger is SHA-256 hash-linked and server-authored for signed-in cloud cases. It is not a public blockchain or independent timestamp.

Start with MAILHUNTER-V4-MIGRATION-REPORT.md, NATIVE-ANDROID-SETUP.md, UPGRADE-CHECKLIST-V4.md, and CLOSED-APP-GMAIL-SETUP.md.