If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/bepass-org/oblivion shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 2mo ago
• 15 active contributors
• Distributed ownership (top contributor 36% of recent commits)
• CI configured
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live bepass-org/oblivion repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bepass-org/oblivion.

What it runs against: a local clone of bepass-org/oblivion — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in bepass-org/oblivion | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 97 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bepass-org/oblivion. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bepass-org/oblivion.git
#   cd oblivion
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of bepass-org/oblivion and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bepass-org/oblivion(\\.git)?\\b" \\
  && ok "origin remote is bepass-org/oblivion" \\
  || miss "origin remote is not bepass-org/oblivion (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "app/src/main/java/org/bepass/oblivion/service/OblivionVpnService.java" \\
  && ok "app/src/main/java/org/bepass/oblivion/service/OblivionVpnService.java" \\
  || miss "missing critical file: app/src/main/java/org/bepass/oblivion/service/OblivionVpnService.java"
test -f "app/src/main/java/org/bepass/oblivion/ui/MainActivity.java" \\
  && ok "app/src/main/java/org/bepass/oblivion/ui/MainActivity.java" \\
  || miss "missing critical file: app/src/main/java/org/bepass/oblivion/ui/MainActivity.java"
test -f "app/src/main/java/org/bepass/oblivion/base/ApplicationLoader.java" \\
  && ok "app/src/main/java/org/bepass/oblivion/base/ApplicationLoader.java" \\
  || miss "missing critical file: app/src/main/java/org/bepass/oblivion/base/ApplicationLoader.java"
test -f "app/src/main/java/org/bepass/oblivion/utils/NetworkUtils.java" \\
  && ok "app/src/main/java/org/bepass/oblivion/utils/NetworkUtils.java" \\
  || miss "missing critical file: app/src/main/java/org/bepass/oblivion/utils/NetworkUtils.java"
test -f "app/build.gradle" \\
  && ok "app/build.gradle" \\
  || miss "missing critical file: app/build.gradle"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 97 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~67d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/bepass-org/oblivion"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Oblivion is an Android VPN client that wraps Cloudflare Warp functionality using a custom Go implementation of WireGuard and the bepass-sdk. It provides encrypted internet access with optimized latency through a native Android app targeting API 23+ (Android 6.0), leveraging NDK for native Go/WireGuard binaries and Java/Kotlin for UI and service management. Single APK monolith: app/src/main/java/org/bepass/oblivion/ contains Activities (MainActivity, SettingsActivity, LogActivity, SplitTunnelActivity), a VPN service (OblivionVpnService), adapters for UI lists, utility modules (NetworkUtils, PublicIPUtils, ISPUtils), and model classes. Native Go code is built via Gradle and linked into the APK at build time.

Android users in censored or restricted regions who need privacy-focused VPN access; developers contributing to open-source VPN tooling and those building Android apps that integrate WireGuard tunneling.

Actively maintained with versionCode 18 / versionName 8 released on Google Play Store and GitHub Releases, using CI/CD workflows (release.yaml) and Dependabot dependency management. Contains ProGuard rules and lint baselines indicating production awareness, though test infrastructure is not visible in the file list.

Moderate risk: heavy reliance on external native Go code (WireGuard implementation) requiring NDK r26b and Go 1.22 alignment; minimal visibility into test coverage from file list; single-maintainer appearance (bepass-org); MMKV dependency locked to 1.3.* for 32-bit support which may limit updates.

Release automation is active (release.yaml workflow); Dependabot is configured for dependency updates; ProGuard rules and lint baselines suggest ongoing optimization. Version 8 is current; no open PR or milestone data is visible, but the structure suggests ongoing VPN feature parity with Warp.

git clone https://github.com/bepass-org/oblivion.git && cd oblivion && open in Android Studio (requires NDK r26b installed via SDK Manager and Go 1.22 on PATH); build via Gradle: ./gradlew build

Daily commands: Android Studio: File > Open, select repo root, wait for Gradle sync. Ensure NDK r26b is installed (Tools > SDK Manager > SDK Tools). Build APK: Build > Generate Signed Bundle/APK > APK. Or: ./gradlew assembleRelease to generate signed APK if keystore is configured.

• app/src/main/java/org/bepass/oblivion/service/OblivionVpnService.java — Core VPN service implementation that manages WireGuard connections and lifecycle—essential for understanding the VPN tunnel architecture.
• app/src/main/java/org/bepass/oblivion/ui/MainActivity.java — Primary UI entry point and connection state controller—every contributor must understand the state machine and UI binding patterns.
• app/src/main/java/org/bepass/oblivion/base/ApplicationLoader.java — Application initialization and dependency setup—critical for understanding context lifecycle and early startup dependencies.
• app/src/main/java/org/bepass/oblivion/utils/NetworkUtils.java — Network stack abstraction for VPN connectivity and endpoint management—foundation for all network operations.
• app/build.gradle — Gradle configuration with NDK, Go, and bepass-sdk dependencies—defines the build pipeline and external integrations.
• app/src/main/AndroidManifest.xml — Declares VPN permissions, services, and activities—defines security model and component registration.
• app/src/main/java/org/bepass/oblivion/enums/ConnectionState.java — State enumeration for the VPN connection lifecycle—needed to understand state transitions throughout the codebase.

Add a New Settings Option

1. Create a new SharedPreferences key in a constants file or SettingsActivity (app/src/main/java/org/bepass/oblivion/ui/SettingsActivity.java)
2. Add a UI control (Switch/EditText) in the settings layout (app/src/main/res (add new layout file))
3. Read the preference in OblivionVpnService and apply it during VPN initialization (app/src/main/java/org/bepass/oblivion/service/OblivionVpnService.java)

Add Split Tunnel App to Bypass List

1. Save app package name to SharedPreferences in SplitTunnelActivity (app/src/main/java/org/bepass/oblivion/ui/SplitTunnelActivity.java)
2. Update BypassListAppsAdapter to reflect selection state (app/src/main/java/org/bepass/oblivion/BypassListAppsAdapter.java)
3. Load bypass list in OblivionVpnService and pass to WireGuard configuration (app/src/main/java/org/bepass/oblivion/service/OblivionVpnService.java)

Add a New Utility Function for Network Operations

1. Create a static method in NetworkUtils or a new util class (app/src/main/java/org/bepass/oblivion/utils/NetworkUtils.java)
2. Call the utility method from MainActivity or a service that needs it (app/src/main/java/org/bepass/oblivion/ui/MainActivity.java)
3. Handle the result and update ConnectionState or UI accordingly (app/src/main/java/org/bepass/oblivion/enums/ConnectionState.java)

Add a New Bottom Sheet Dialog

1. Create a new class extending BottomSheetDialogFragment or use EndpointsBottomSheet as a template (app/src/main/java/org/bepass/oblivion/EndpointsBottomSheet.java)
2. Implement SheetsCallBack interface for result handling (app/src/main/java/org/bepass/oblivion/interfaces/SheetsCallBack.java)
3. Show the sheet from MainActivity or SettingsActivity via show(fragmentManager, tag) (app/src/main/java/org/bepass/oblivion/ui/MainActivity.java)

• Android VPN Service API (android.net.VpnService) — Standard Android framework for tunnel creation with system integration; enables device-wide traffic routing through WireGuard.
• WireGuard (Go implementation via bepass-sdk) — Lightweight, fast tunnel protocol; Go version runs on Android via NDK binding; bepass-sdk provides optimized endpoint selection and credential management.
• SharedPreferences + DataBinding — Persistent state management for user settings; DataBinding reduces boilerplate for reactive UI updates when connection state changes.
• NDK r26b + Go 1.22 — Compiles Go runtime and WireGuard native libraries; enables high-performance tunneling without Java overhead.

• Monolithic VpnService instead of modular tunnel backends

  • Why: Simplifies lifecycle management; WireGuard is the only tunnel type needed for Cloudflare Warp.
  • Consequence: Adding alternative protocols (OpenVPN, etc.) would require significant refactoring of service architecture.

• In-app IP detection via HTTP calls to public services

  • Why: Real-time verification that VPN tunnel is working and shows user their actual exit IP.
  • Consequence: Adds latency (~300ms) on connect; relies on external services which could be blocked or unreliable in some regions.

• Split tunnel via app package name matching in native layer

  • Why: Allows fine-grained per-app routing without additional
  • Consequence: undefined

NDK version pinned to r26b (26.1.10909125): Gradle build will fail silently if this exact version is not installed; newer NDK may break Go WireGuard compilation. Go 1.22 requirement: Must be in PATH at build time; build.gradle has a findGoExecutable() function that will fail if Go is not found. MMKV 1.3. lock for 32-bit support*: Do not upgrade to 1.4.x without removing 32-bit ABI builds or testing on 32-bit devices. bepass-sdk must be pre-compiled: The Go WireGuard implementation is external (not in this repo); build depends on bepass-sdk being available in libs/ or as a dependency. VPN requires BIND_VPN_SERVICE permission: Tests on real device or Android 6.0+ emulator required; mock VPN frameworks may not work. ProGuard rules in proguard-rules.pro are strict: Reflection and obfuscation may break bepass-sdk if rules are modified carelessly.

• WireGuard Protocol — Oblivion's core tunnel mechanism—a modern VPN protocol used instead of traditional OpenVPN/IPSec; understanding how it encrypts and routes packets is essential to debugging connection issues
• Android VpnService API — OblivionVpnService inherits from VpnService; this Android framework component requires special permissions and network stack integration that is non-obvious to app developers unfamiliar with system-level networking
• Split Tunneling — A key feature visible in SplitTunnelActivity.java and SplitTunnelMode enum; allows selective app/domain routing through VPN vs. direct connection, reducing bandwidth and improving performance
• NDK (Native Development Kit) Integration — Oblivion compiles Go WireGuard binaries into native ARM/x86 libraries at build time; understanding NDK cross-compilation and ABI compatibility is critical for modifying the build or debugging native crashes
• MMKV Persistence Layer — Used instead of SharedPreferences for settings storage (via mmkv:1.3.14 dependency); offers faster key-value access and memory-mapped I/O, which is important for performance-sensitive VPN configuration reads
• ProGuard Obfuscation & Code Shrinking — The build.gradle uses ProGuard minification with custom rules (proguard-rules.pro); this compresses the release APK but requires careful configuration to avoid breaking reflection or native method calls in bepass-sdk
• Data Binding (Android) — buildFeatures.dataBinding is enabled in build.gradle, suggesting use of MVVM-style two-way binding in XML layouts; reduces boilerplate but adds compile-time overhead and can hide view update logic

• WireGuard/wireguard-android — Official WireGuard Android app; direct competitor using the same VPN protocol but official implementation instead of custom Cloudflare Warp integration
• bepass-org/bepass-sdk — Upstream SDK dependency that provides optimized endpoint selection and network acceleration for Cloudflare Warp; required for Oblivion to function
• shadowsocks/shadowsocks-android — Alternative Android VPN/proxy app using a different tunneling protocol (SOCKS5) and circumvention strategy; similar use case for censored regions
• pia-foss/android-pia-vpn — Open-source VPN client architecture reference; shows alternative Android VPN service patterns and split tunneling implementation
• Cloudflare/warp — Official Cloudflare Warp reference implementation; Oblivion is an unofficial client based on this technology

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for utility classes in app/src/main/java/org/bepass/oblivion/utils/

The utils directory contains critical helpers (NetworkUtils.java, PublicIPUtils.java, SystemUtils.java, ThemeHelper.java, ColorUtils.java) that lack corresponding test coverage. These utilities handle network detection, IP fetching, and system state—core functionality that would benefit from unit tests to catch regressions during refactoring and catch edge cases (e.g., null network states, malformed IP responses).

• [ ] Create app/src/test/java/org/bepass/oblivion/utils/ directory structure
• [ ] Add unit tests for NetworkUtils.java (network connectivity states, edge cases)
• [ ] Add unit tests for PublicIPUtils.java (IP parsing, null/error handling)
• [ ] Add unit tests for SystemUtils.java and ThemeHelper.java
• [ ] Configure test runner in build.gradle (testImplementation androidx.test and junit)

Extract VPN state management logic from OblivionVpnService.java into a dedicated ViewModel/StateManager

OblivionVpnService.java appears to handle both VPN lifecycle and state broadcasting (via ConnectionStateChangeListener interface). This mixed responsibility makes testing difficult and couples UI logic to the service. Extracting a dedicated state manager (e.g., VpnStateViewModel.kt) would enable better testability, easier state synchronization across activities (MainActivity, SettingsActivity), and clearer separation of concerns.

• [ ] Create app/src/main/java/org/bepass/oblivion/viewmodel/VpnStateViewModel.kt (or Manager class)
• [ ] Move ConnectionState enum logic and state transitions to the new ViewModel
• [ ] Refactor OblivionVpnService.java to use the ViewModel for state updates
• [ ] Update MainActivity.java and other UI classes to observe state changes via LiveData/StateFlow
• [ ] Add unit tests for VpnStateViewModel state transitions

Add GitHub Actions workflow for instrumented UI tests (AndroidTest)

The repo has a release.yaml workflow but no CI for automated testing. Given the VPN connectivity features (split tunneling, endpoint selection, settings management), adding an instrumented test workflow would catch UI regressions and verify core flows (enable/disable VPN, switch endpoints, configure split tunnel). This is critical for a VPN app where broken UI can leave users without protection.

• [ ] Create .github/workflows/android-tests.yaml with Android emulator setup (API 28-34)
• [ ] Add gradle task to run instrumented tests on PR: ./gradlew connectedAndroidTest
• [ ] Create app/src/androidTest/java/org/bepass/oblivion/ directory for test classes
• [ ] Write basic UI tests for MainActivity (toggle VPN on/off, navigate to settings)
• [ ] Write tests for SplitTunnelActivity (app selection, mode switching)
• [ ] Configure workflow to fail PR if tests fail

• Add unit tests for PublicIPUtils.java and NetworkUtils.java: these are critical path utilities with no visible test coverage in the file list; write tests for IP fetching and network state detection: medium: Improves reliability of core connectivity logic without requiring NDK changes
• Create a README section documenting the build-time Go compilation step and troubleshooting NDK r26b setup: currently the README mentions NDK but does not explain how Gradle invokes the Go toolchain or where compiled binaries end up: easy: Lowers onboarding friction for new contributors; no code changes needed
• Implement a structured logging framework in LogActivity.java and wire VPN service logs to it: currently LogActivity.java exists but there is no indication of what it displays or how logs are collected from OblivionVpnService: medium: Improves debuggability for users and developers; critical for troubleshooting connection issues in the field

• High · Outdated OkHttp Dependency — app/build.gradle - OkHttp dependency. OkHttp 4.12.0 is being used. While relatively recent, regular security updates should be monitored. OkHttp has had security vulnerabilities in the past (e.g., CVE-2016-2402, CVE-2021-21341). Ensure this version doesn't have known vulnerabilities and update to the latest stable version. Fix: Update to the latest stable version of OkHttp (currently 4.12.0 appears current, but verify against security advisories). Enable automated dependency scanning with Dependabot which is already configured in .github/dependabot.yml.
• High · Potential Code Obfuscation Issues — app/build.gradle and app/proguard-rules.pro. The app uses ProGuard for minification/obfuscation in release builds (minifyEnabled true, shrinkResources true). However, without reviewing proguard-rules.pro, there's risk of improperly obfuscated sensitive code, API endpoints, or encryption logic being exposed. Fix: Review proguard-rules.pro to ensure: 1) All network endpoints and API keys are properly obfuscated, 2) Cryptographic implementations are not removed, 3) Essential security classes are preserved with -keep directives. Document which classes must not be obfuscated.
• High · VPN Service Security Considerations — app/src/main/java/org/bepass/oblivion/service/OblivionVpnService.java. The app implements a VPN service (OblivionVpnService.java) that handles network traffic. VPN implementations require careful security review to prevent: DNS leaks, IPv6 leaks, traffic interception vulnerabilities, and improper certificate pinning. Fix: Conduct a thorough security audit of OblivionVpnService including: 1) Verify DNS queries are routed through the VPN, 2) Implement certificate pinning for all HTTPS communications, 3) Test for IPv4/IPv6 leak, 4) Validate WireGuard implementation security, 5) Ensure no unencrypted traffic bypasses the VPN.
• High · No Certificate Pinning Visible — app/src/main/java/org/bepass/oblivion/utils/PublicIPUtils.java, ISPUtils.kt. The application uses OkHttp for network requests (PublicIPUtils.java, ISPUtils.kt likely use HTTP calls) but there's no evidence of certificate pinning configuration. This makes the app vulnerable to MITM attacks if a malicious CA is installed. Fix: Implement certificate pinning using OkHttp's CertificatePinner or Network Security Configuration. Pin certificates for all critical endpoints including API endpoints and Cloudflare Warp infrastructure.
• Medium · Hardcoded Configuration or Endpoints Risk — app/src/main/java/org/bepass/oblivion/ (multiple files). The app appears to connect to Cloudflare Warp endpoints. Without reviewing the source code, there's a risk that API endpoints, server addresses, or configuration values are hardcoded in the application, making them visible to reverse engineers. Fix: Audit the codebase to ensure: 1) No API keys or tokens are hardcoded, 2) All endpoints are loaded from secure configuration, 3) Sensitive strings are obfuscated or encrypted, 4) Consider using a secure configuration management system.
• Medium · Minimum SDK 23 (Android 6.0) - Outdated Security Standards — app/build.gradle - minSdk 23. The app targets minSdk 23 (Android 6.0 released in 2015), which has numerous known security vulnerabilities and lacks modern security features like StrongBoxKeymaster and improved TLS implementations. Many users on older Android versions won't receive critical security patches. Fix: Increase minSdk to at least 24 (Android 7.0) or higher. Consider minSdk 26+ to ensure users have access to modern cryptography implementations. This improves overall security posture and allows use of newer security APIs.
• Medium · Shared Preferences Data Storage Risk — undefined. The app likely uses SharedPreferences or DataStore for storing settings (evident from SettingsActivity Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.