{"id":23388244,"url":"https://github.com/sovereign-engineering/obscuravpn-client","last_synced_at":"2025-04-06T16:10:24.198Z","repository":{"id":266360880,"uuid":"895691406","full_name":"Sovereign-Engineering/obscuravpn-client","owner":"Sovereign-Engineering","description":"Obscura VPN Rust library and App (macOS only for now)","archived":false,"fork":false,"pushed_at":"2025-03-31T17:13:11.000Z","size":1316,"stargazers_count":119,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T06:07:05.615Z","etag":null,"topics":["macos","quic","rust","wireguard"],"latest_commit_sha":null,"homepage":"https://obscura.net","language":"Swift","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sovereign-Engineering.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-28T17:33:01.000Z","updated_at":"2025-04-05T12:23:55.000Z","dependencies_parsed_at":"2024-12-18T19:35:44.485Z","dependency_job_id":"88f76f21-6a53-4ca5-a75a-96e1c87e1bfc","html_url":"https://github.com/Sovereign-Engineering/obscuravpn-client","commit_stats":null,"previous_names":["sovereign-engineering/obscuravpn-client"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sovereign-Engineering%2Fobscuravpn-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sovereign-Engineering%2Fobscuravpn-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sovereign-Engineering%2Fobscuravpn-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sovereign-Engineering%2Fobscuravpn-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sovereign-Engineering","download_url":"https://codeload.github.com/Sovereign-Engineering/obscuravpn-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247509221,"owners_count":20950232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["macos","quic","rust","wireguard"],"created_at":"2024-12-22T02:18:21.179Z","updated_at":"2025-04-06T16:10:24.175Z","avatar_url":"https://github.com/Sovereign-Engineering.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Obscura VPN Client\n\nObscura VPN library, CLI client, and App\n\n## Support\n\nNo support is provided for this code directly. However, if you are experiencing issues with your Obscura VPN service please contact \u003csupport@obscura.net\u003e.\n\n## Contributions\n\nAt this time we are unable to accept external contributions. This is something that we plan to resolve soon. However until we finish the paperwork we are unable to look at any patches and will close all PRs without looking at them.\n\n# macOS App\n\nOn macOS the app installs and manages a [network extension](https://developer.apple.com/documentation/networkextension) (system extension).\nThe network extension manages the virtual device and maintains the tunnel using the Rust code as library.\n\n## Setup\n\n1. [Install `rustup`](https://rustup.rs/).\n1. [Setup Nix](#nix-setup)\n1. Open the main Xcode project\n    ```bash\n    nix develop --print-build-logs --command just xcode-open\n    ```\n1. In Xcode, login with an account with membership in \"Sovereign Engineering Inc.\"\n1. Register development machine in Apple Developer portal (can be done in Xcode)\n1. [Enable system extension developer mode](#enabling-system-extension-developer-mode)\n1. Setup Developer ID provisioning profile and codesigning for `Prod Client` build scheme\n    1. Go to https://developer.apple.com/account/resources/profiles/list\n        - Download \"Developer ID: System Network Extension\"\n        - Download \"Developer ID: VPN Client App\"\n    1. Install both provisioning profiles by double-clicking them.\n    1. Ask Carl to send the Developer ID codesigning certificate and the corresponding password\n    1. Double click the certificate, enter the password, and install it to your \"login\" keychain\n\n## Building and Running\n\n1. Open the main Xcode project:\n    ```bash\n    nix develop --print-build-logs --command just xcode-open\n    ```\n1. Pick a build scheme using Xcode's GUI, one of:\n\n    ℹ️ **INFO**: Xcode differentiates between \"build schemes\" and \"build configurations\", see [Apple's docs on this](https://developer.apple.com/documentation/xcode/build-system) for more details.\n\n    1. `Dev Client`: Development Client\n\n        General purpose for development. Uses the main UI with additional developer and pre-release features exposed.\n\n        Uses the `Debug*` build configurations. Codesigned with the `Apple Development` xcode-managed identity.\n\n        ⚠️ **WARNING**: When using this build scheme, make sure you are quitting the app via the top-right status menu bar and **NOT** using Xcode's \"Stop\" as doing so does not actually stop the dev server. This is because stopping via Xcode doesn't run the build scheme's \"Run → Post-actions\"\n\n    1. `Prod Client`: The App with a static web bundle\n\n        Useful for reproducing what the final shippable app will look like and be built as.\n\n        Uses the `Release*` build configurations. Codesigned with the `Developer ID Application: Sovereign Engineering Inc. (5G943LR562)` manually-managed identity.\n\n        The static web bundle built with the build scheme's \"Build → Pre-actions\".\n\n        If you encounter trouble with this build scheme, especially with codesigning or provisioning profiles:\n\n        1. Make sure that you've completed the relevant steps in [setup](#setup)\n        1. See additional instructions in [Confirming \"Developer ID\" Setup](#confirming-developer-id-setup)\n\n    1. `Bare Client`: The App with a minimal HTML UI\n\n        Useful for fine-grain control and debugging.\n\n        Uses the `Debug*` build configurations. Codesigned with the `Apple Development` xcode-managed identity.\n\n1. Build or Run the App\n\n    - `⌘ + B` (Build), or\n    - `⌘ + R` (Run)\n\n    💡 **TIP**: It may initially _seem_ like Xcode is doing nothing when you run or build, but it may just be running the build scheme's \"Pre-actions\", see the \"Report navigator\" in Xcode's top-left app menu: \"View → Navigators → Reports\" to track the actual status.\n\n    💡 **TIP**: If a build fails with `could not find included file 'buildversion.xcconfig' in search paths`, see the [relevant troubleshooting entry](#error-on-build-in-clean-repo-could-not-find-included-file-buildversionxcconfig-in-search-paths).\n\n    -----\n\n    Xcode places built products in a deeply nested directory structure that it controls, with seperate folders for each build configuration. The easiest way to locate where the app is:\n\n    1. \"Run\" the app\n    1. Once the app's icon appears on the macOS Dock, `⌘-Click` the app icon to reveal it in the finder.\n\n💡 **TIP**: It is highly recommended to read through various sections in [Development Tips](#development-tips) to better understand the various ways we've configured the Xcode build system to work with our development process.\n\n## Debugging\n\n### Logs\n\nBoth app and network extension logs are available via [Apple's unified logging system](https://developer.apple.com/documentation/os/logging).\n\n#### Analyzing Logs\n\nThere are tools for analyzing logs available as `bin/log-*`. They accept log files in JSON lines format. This can be found in the app's Debug Bundle or from the Apple `log` command by specifying `--style=ndjson`.\n\nThe main tool is `bin/log-text.py` which just turns the logs into a readable text format as well as applying some basic filtering with a few CLI options to apply more filters. Other tools are available, run with `--help` to get information about what they do.\n\nFor more in-depth analysis you are likely best using the tools as a starting point and modifying them as needed or using other tools like `jq`, `sqlite` or `duckdb`. If your analysis is generally useful consider committing it.\n\n#### Stream Logs\n\nThis will output logs starting at the point in time when you run this command:\n\n```bash\nlog stream --info --debug --predicate 'process CONTAINS[c] \"obscura\" || subsystem CONTAINS[c] \"obscura\"'\n```\n\n#### View Past Logs\n\n\u003e [!WARNING]\n\u003e Since Apple may or may not persist logs at the `INFO` or `DEBUG` level, logs at these level might be lost. See [Apple's developer docs on this](https://developer.apple.com/documentation/os/logging/generating_log_messages_from_your_code#3665947) for more information.\n\u003e\n\u003e You may be able to set a log configuration to ensure that these logs are persisted, though this has not been tested, please update this `README` with instructions if you successfully test this. See [Apple's docs on \"Customizing Logging Behavior While Debugging\"](https://developer.apple.com/documentation/os/logging/customizing_logging_behavior_while_debugging) for more information.\n\n```bash\nlog show --last 200 --info --debug --color always --predicate 'process CONTAINS[c] \"obscura\" || subsystem CONTAINS[c] \"obscura\"' | less +G -R\n```\n\n#### UserDefaults\n\n```sh\ndefaults read \"net.obscura.vpn-client-app\"\n# delete all defaults including Sparkle related keys (SU*)\ndefaults delete-all \"net.obscura.vpn-client-app\"\n# delete keys individually\ndefaults delete \"net.obscura.vpn-client-app\" \u003ckey\u003e\n```\n\n## Running Checks\n\n### Linting\n\n```bash\nnix develop --print-build-logs --command just lint\n```\n\n### Formatting\n\n#### Checking\n\n```bash\nnix develop --print-build-logs --command just format-check\n```\n\n#### Auto-fixing\n\n```bash\nnix develop --print-build-logs --command just format-fix\n```\n\n## Building a Notarized Disk Image\n\n1. Save authentication credentials for the Apple notary service (only need to do once)\n\n    ```bash\n    xcrun notarytool store-credentials \"notarytool-password\" --team-id 5G943LR562\n    ```\n\n    Use [appleid.apple.com](https://appleid.apple.com/account/manage) --\u003e App-Specific Passwords\n\n1. (OPTIONAL) If we're doing a release, tag the version `git tag -s v/1.23 -m v/1.23 \u0026\u0026 git push --tags`.\n1. Unlock the \"Login\" keychain: `security unlock-keychain`\n1. Build the signed and notarized disk image: `just build-dmg`\n\n    💡 **TIP**: This command uses AppleScript automation of Finder to change the background of Disk Images, so Finder windows may open.\n\n    The built disk image will appear in the current working directory as \"Obscura VPN.dmg\"\n\n## Troubleshooting\n\n### `cargo` not rebuilding when it should\n\nA lot of Xcode-set properties don't properly trigger a rebuild from `cargo` even\nthough they're supposed to. The most prominent of which is `MACOSX_DEPLOYMENT_TARGET`.\n\nThis is easily worked-around by \"Product → Clean Build Folder...\" in Xcode then rerunning the build.\n\nUpstream status on this:\n- https://github.com/rust-lang/cc-rs/issues/906\n- https://github.com/rust-lang/rust/issues/118204\n\n## Development Tips\n\n### Enabling system extension developer mode\n\nThis is necessary for:\n- The `systemextensionsctl` commands to work, and\n- To allow installing and running system extensions from places other than `/Applications`\n\nAccording to [Apple's docs for system extensions](https://developer.apple.com/documentation/driverkit/debugging_and_testing_system_extensions#3557204), as of 2024-07-04:\n\n\u003e You must place all system extensions in the `Contents/Library/SystemExtensions` directory of your app bundle, and the app itself must be installed in one of the system’s `Applications` directories. To allow development of your app outside of these directories, use the `systemextensionsctl` command-line tool to enable developer mode. When in developer mode, the system doesn't check the location of your system extension prior to loading it, so you can load it from anywhere in the file system.\n\nTo accomplish this:\n1. [Disable system integrity protection](https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection)\n1. Then, run\n    ```bash\n    systemextensionsctl developer on\n    ```\n\n### Removing network extension (system extension)\n\n1. Ensure that [system extension developer mode is enabled](#enabling-system-extension-developer-mode)\n1. Then, run\n    ```bash\n    systemextensionsctl uninstall 5G943LR562 net.obscura.vpn-client-app.system-network-extension\n    ```\n\n### Nix Setup\n\n- Install [`nix`](https://nixos.org/download/) (only the package manager is needed)\n- Enable [`flake`s](https://nixos.wiki/wiki/Flakes)\n\n    Add the following to `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`:\n\n    ```\n    experimental-features = nix-command flakes\n    ```\n\n- Optional, but strongly recommended: Set up [`nix-direnv`](https://github.com/nix-community/nix-direnv) and integrate it with your preferred shell\n\n  If you do this, you can omit the `nix develop ... --command` parts, as `cd`-ing into the repository directory will set up your environment variables with the correct tools as long as you've `direnv allow`-ed the directory.\n\n### Confirming \"Developer ID\" Setup\n\nTo confirm that the Developer ID provisioning profile and codesigning are set up correctly (required for the `Prod Client` build scheme):\n\n1. Pick the `Prod Client` build scheme in Xcode\n1. Create an Archive\n    Choose from Xcode's top-left app menu: \"Product → Archive\"\n1. Ensure that the \"Archive\" action succeeds in the \"Report navigator\"\n    Choose from Xcode's top-left app menu: \"View → Navigators → Reports\"\n\n## Linux\n\n\u003e [!WARNING]\n\u003e As of 2024-07-04, the Linux client is not maintained.\n\n```bash\ncargo build --release \u0026\u0026 sudo RUST_LOG=info ./target/release/obscuravpn-client\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsovereign-engineering%2Fobscuravpn-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsovereign-engineering%2Fobscuravpn-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsovereign-engineering%2Fobscuravpn-client/lists"}