snakevpn 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. snakevpn-0.0.1/.github/CODEOWNERS +45 -0
  2. snakevpn-0.0.1/.github/dependabot.yml +12 -0
  3. snakevpn-0.0.1/.github/workflows/ci.yml +25 -0
  4. snakevpn-0.0.1/.github/workflows/publish.yml +70 -0
  5. snakevpn-0.0.1/.gitignore +8 -0
  6. snakevpn-0.0.1/AGENTS.md +110 -0
  7. snakevpn-0.0.1/LICENSE +674 -0
  8. snakevpn-0.0.1/PKG-INFO +156 -0
  9. snakevpn-0.0.1/PLAN.md +497 -0
  10. snakevpn-0.0.1/README.md +134 -0
  11. snakevpn-0.0.1/WORKSTREAMS.md +250 -0
  12. snakevpn-0.0.1/docs/.nojekyll +0 -0
  13. snakevpn-0.0.1/docs/index.html +353 -0
  14. snakevpn-0.0.1/docs/index.md +272 -0
  15. snakevpn-0.0.1/docs/llms.txt +21 -0
  16. snakevpn-0.0.1/docs/robots.txt +5 -0
  17. snakevpn-0.0.1/docs/sitemap.xml +6 -0
  18. snakevpn-0.0.1/pyproject.toml +60 -0
  19. snakevpn-0.0.1/src/pyvpn/__init__.py +3 -0
  20. snakevpn-0.0.1/src/pyvpn/__main__.py +3 -0
  21. snakevpn-0.0.1/src/pyvpn/apps/__init__.py +7 -0
  22. snakevpn-0.0.1/src/pyvpn/apps/cgroups.py +77 -0
  23. snakevpn-0.0.1/src/pyvpn/apps/launcher.py +72 -0
  24. snakevpn-0.0.1/src/pyvpn/apps/manager.py +59 -0
  25. snakevpn-0.0.1/src/pyvpn/apps/netns.py +36 -0
  26. snakevpn-0.0.1/src/pyvpn/apps/proc_connector.py +82 -0
  27. snakevpn-0.0.1/src/pyvpn/apps/selectors.py +138 -0
  28. snakevpn-0.0.1/src/pyvpn/apps/watcher.py +134 -0
  29. snakevpn-0.0.1/src/pyvpn/audit/__init__.py +52 -0
  30. snakevpn-0.0.1/src/pyvpn/cli/__init__.py +400 -0
  31. snakevpn-0.0.1/src/pyvpn/cli/install.py +151 -0
  32. snakevpn-0.0.1/src/pyvpn/cli/output.py +116 -0
  33. snakevpn-0.0.1/src/pyvpn/config/__init__.py +40 -0
  34. snakevpn-0.0.1/src/pyvpn/config/errors.py +22 -0
  35. snakevpn-0.0.1/src/pyvpn/config/loader.py +83 -0
  36. snakevpn-0.0.1/src/pyvpn/config/migrations.py +49 -0
  37. snakevpn-0.0.1/src/pyvpn/config/models.py +236 -0
  38. snakevpn-0.0.1/src/pyvpn/constants.py +50 -0
  39. snakevpn-0.0.1/src/pyvpn/daemon/__init__.py +1 -0
  40. snakevpn-0.0.1/src/pyvpn/daemon/api.py +109 -0
  41. snakevpn-0.0.1/src/pyvpn/daemon/client.py +173 -0
  42. snakevpn-0.0.1/src/pyvpn/daemon/core.py +487 -0
  43. snakevpn-0.0.1/src/pyvpn/daemon/persistence.py +107 -0
  44. snakevpn-0.0.1/src/pyvpn/daemon/planner.py +94 -0
  45. snakevpn-0.0.1/src/pyvpn/daemon/reconciler.py +541 -0
  46. snakevpn-0.0.1/src/pyvpn/daemon/server.py +223 -0
  47. snakevpn-0.0.1/src/pyvpn/dns/__init__.py +1 -0
  48. snakevpn-0.0.1/src/pyvpn/dns/aliases.py +78 -0
  49. snakevpn-0.0.1/src/pyvpn/dns/service.py +526 -0
  50. snakevpn-0.0.1/src/pyvpn/dns/upstream.py +195 -0
  51. snakevpn-0.0.1/src/pyvpn/match/__init__.py +69 -0
  52. snakevpn-0.0.1/src/pyvpn/match/asn.py +127 -0
  53. snakevpn-0.0.1/src/pyvpn/match/opts.py +277 -0
  54. snakevpn-0.0.1/src/pyvpn/match/pattern.py +595 -0
  55. snakevpn-0.0.1/src/pyvpn/match/policy.py +305 -0
  56. snakevpn-0.0.1/src/pyvpn/match/route.py +502 -0
  57. snakevpn-0.0.1/src/pyvpn/match/ruleset.py +331 -0
  58. snakevpn-0.0.1/src/pyvpn/platform/__init__.py +1 -0
  59. snakevpn-0.0.1/src/pyvpn/platform/base.py +33 -0
  60. snakevpn-0.0.1/src/pyvpn/platform/linux/__init__.py +1 -0
  61. snakevpn-0.0.1/src/pyvpn/platform/linux/dns.py +25 -0
  62. snakevpn-0.0.1/src/pyvpn/platform/linux/netlink.py +353 -0
  63. snakevpn-0.0.1/src/pyvpn/py.typed +0 -0
  64. snakevpn-0.0.1/src/pyvpn/routing/__init__.py +1 -0
  65. snakevpn-0.0.1/src/pyvpn/routing/plan.py +113 -0
  66. snakevpn-0.0.1/src/pyvpn/rulefile/__init__.py +21 -0
  67. snakevpn-0.0.1/src/pyvpn/rulefile/commands.py +172 -0
  68. snakevpn-0.0.1/src/pyvpn/rulefile/file.py +274 -0
  69. snakevpn-0.0.1/src/pyvpn/services.py +61 -0
  70. snakevpn-0.0.1/src/pyvpn/state.py +84 -0
  71. snakevpn-0.0.1/src/pyvpn/targets/__init__.py +16 -0
  72. snakevpn-0.0.1/src/pyvpn/targets/probes.py +58 -0
  73. snakevpn-0.0.1/src/pyvpn/targets/resolver.py +30 -0
  74. snakevpn-0.0.1/src/pyvpn/targets/watcher.py +102 -0
  75. snakevpn-0.0.1/tests/__init__.py +1 -0
  76. snakevpn-0.0.1/tests/apps/conftest.py +16 -0
  77. snakevpn-0.0.1/tests/apps/test_cgroups.py +30 -0
  78. snakevpn-0.0.1/tests/apps/test_launcher.py +41 -0
  79. snakevpn-0.0.1/tests/apps/test_manager.py +45 -0
  80. snakevpn-0.0.1/tests/apps/test_netns.py +13 -0
  81. snakevpn-0.0.1/tests/apps/test_proc_connector.py +13 -0
  82. snakevpn-0.0.1/tests/apps/test_selectors.py +89 -0
  83. snakevpn-0.0.1/tests/apps/test_watcher.py +169 -0
  84. snakevpn-0.0.1/tests/cli/__init__.py +0 -0
  85. snakevpn-0.0.1/tests/cli/test_cli.py +426 -0
  86. snakevpn-0.0.1/tests/cli/test_install.py +144 -0
  87. snakevpn-0.0.1/tests/config/__init__.py +0 -0
  88. snakevpn-0.0.1/tests/config/test_loader.py +80 -0
  89. snakevpn-0.0.1/tests/contracts/__init__.py +1 -0
  90. snakevpn-0.0.1/tests/contracts/test_config.py +326 -0
  91. snakevpn-0.0.1/tests/contracts/test_constants.py +22 -0
  92. snakevpn-0.0.1/tests/contracts/test_fakes.py +20 -0
  93. snakevpn-0.0.1/tests/daemon/__init__.py +1 -0
  94. snakevpn-0.0.1/tests/daemon/conftest.py +55 -0
  95. snakevpn-0.0.1/tests/daemon/test_client.py +186 -0
  96. snakevpn-0.0.1/tests/daemon/test_daemon.py +1006 -0
  97. snakevpn-0.0.1/tests/daemon/test_planner.py +107 -0
  98. snakevpn-0.0.1/tests/daemon/test_reconciler.py +430 -0
  99. snakevpn-0.0.1/tests/dns/_helpers.py +25 -0
  100. snakevpn-0.0.1/tests/dns/test_namespace.py +288 -0
  101. snakevpn-0.0.1/tests/dns/test_service.py +1139 -0
  102. snakevpn-0.0.1/tests/dns/test_upstream.py +229 -0
  103. snakevpn-0.0.1/tests/fakes/__init__.py +15 -0
  104. snakevpn-0.0.1/tests/fakes/_stream.py +33 -0
  105. snakevpn-0.0.1/tests/fakes/apps.py +34 -0
  106. snakevpn-0.0.1/tests/fakes/backend.py +40 -0
  107. snakevpn-0.0.1/tests/fakes/dns.py +27 -0
  108. snakevpn-0.0.1/tests/fakes/rules.py +17 -0
  109. snakevpn-0.0.1/tests/fakes/targets.py +25 -0
  110. snakevpn-0.0.1/tests/routing/test_plan.py +109 -0
  111. snakevpn-0.0.1/tests/targets/test_netlink_reader.py +190 -0
  112. snakevpn-0.0.1/tests/targets/test_targets.py +378 -0
  113. snakevpn-0.0.1/tests/vectors/__init__.py +0 -0
  114. snakevpn-0.0.1/tests/vectors/conftest.py +22 -0
  115. snakevpn-0.0.1/tests/vectors/test_match.py +353 -0
  116. snakevpn-0.0.1/tests/vectors/test_policy_matcher.py +330 -0
  117. snakevpn-0.0.1/tests/vectors/test_route.py +375 -0
  118. snakevpn-0.0.1/tests/vectors/test_rulefile.py +149 -0
@@ -0,0 +1,45 @@
1
+ # Stream A - Config & CLI
2
+ /src/pyvpn/config/ @cpu-catten
3
+ /src/pyvpn/cli/ @cpu-catten
4
+
5
+ # Stream B - Daemon core
6
+ /src/pyvpn/daemon/ @irisariuan
7
+ /src/pyvpn/daemon/client.py @cpu-catten
8
+
9
+ # Stream C - Linux routing & netfilter
10
+ /src/pyvpn/netfilter/ @Daydreaming-Mr
11
+ /src/pyvpn/routing/ @Daydreaming-Mr
12
+ /src/pyvpn/platform/linux/backend.py @Daydreaming-Mr
13
+
14
+ # Stream D - Targets
15
+ /src/pyvpn/targets/ @JackyCheng0006
16
+ /src/pyvpn/platform/linux/netlink.py @JackyCheng0006
17
+
18
+ # Stream E - Apps
19
+ /src/pyvpn/apps/ @JovoJ-c
20
+
21
+ # Stream F - DNS & leak protection
22
+ /src/pyvpn/dns/ @Daydreaming-Mr
23
+ /src/pyvpn/audit/ @Daydreaming-Mr
24
+ /src/pyvpn/platform/linux/dns.py @Daydreaming-Mr
25
+
26
+ # Stream G - Rule engine
27
+ /src/pyvpn/match/ @irisariuan
28
+ /src/pyvpn/rulefile/ @irisariuan
29
+ /tests/vectors/ @irisariuan
30
+
31
+ # Stream I - Test bed, CI & release
32
+ /tests/integration/ @cpu-catten
33
+ /tests/conftest.py @cpu-catten
34
+ /tests/ci/ @cpu-catten
35
+ /pyproject.toml @cpu-catten
36
+ /.github/ @cpu-catten
37
+
38
+ # Shared Phase 0 contracts
39
+ /src/pyvpn/constants.py @cpu-catten @irisariuan @Daydreaming-Mr @JackyCheng0006 @JovoJ-c
40
+ /src/pyvpn/config/models.py @cpu-catten @irisariuan @Daydreaming-Mr @JackyCheng0006 @JovoJ-c
41
+ /src/pyvpn/state.py @cpu-catten @irisariuan @Daydreaming-Mr @JackyCheng0006 @JovoJ-c
42
+ /src/pyvpn/platform/base.py @cpu-catten @irisariuan @Daydreaming-Mr @JackyCheng0006 @JovoJ-c
43
+ /src/pyvpn/daemon/api.py @cpu-catten @irisariuan @Daydreaming-Mr @JackyCheng0006 @JovoJ-c
44
+ /src/pyvpn/services.py @cpu-catten @irisariuan @Daydreaming-Mr @JackyCheng0006 @JovoJ-c
45
+ /tests/fakes/ @cpu-catten @irisariuan @Daydreaming-Mr @JackyCheng0006 @JovoJ-c
@@ -0,0 +1,12 @@
1
+ version: 2
2
+
3
+ updates:
4
+ - package-ecosystem: github-actions
5
+ directory: /
6
+ schedule:
7
+ interval: weekly
8
+
9
+ - package-ecosystem: pip
10
+ directory: /
11
+ schedule:
12
+ interval: weekly
@@ -0,0 +1,25 @@
1
+ # Phase 0 CI skeleton. Stream I adds the root netns job and the release workflow.
2
+ name: CI
3
+
4
+ on:
5
+ push:
6
+ branches: [main]
7
+ pull_request:
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-24.04
12
+ strategy:
13
+ fail-fast: false
14
+ matrix:
15
+ python: ["3.11", "3.12", "3.13", "3.14"]
16
+ steps:
17
+ - uses: actions/checkout@v7
18
+ - uses: actions/setup-python@v7
19
+ with:
20
+ python-version: ${{ matrix.python }}
21
+ - run: pip install -e '.[dev]'
22
+ - run: ruff check .
23
+ - run: ruff format --check .
24
+ - run: mypy src
25
+ - run: pytest
@@ -0,0 +1,70 @@
1
+ # Build and publish snakevpn to PyPI when a GitHub Release is published.
2
+ # Uses PyPI Trusted Publishing (OIDC): no API token is stored in the repo.
3
+ # One-time setup on PyPI: add a trusted publisher for irisariuan/pyvpn,
4
+ # workflow "publish.yml", environment "pypi".
5
+ name: Publish to PyPI
6
+
7
+ on:
8
+ release:
9
+ types: [published]
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ jobs:
15
+ test:
16
+ runs-on: ubuntu-24.04
17
+ strategy:
18
+ fail-fast: true
19
+ matrix:
20
+ python: ["3.11", "3.12", "3.13"]
21
+ steps:
22
+ - uses: actions/checkout@v7
23
+ - uses: actions/setup-python@v7
24
+ with:
25
+ python-version: ${{ matrix.python }}
26
+ - run: pip install -e '.[dev]'
27
+ - run: ruff check .
28
+ - run: ruff format --check .
29
+ - run: mypy src
30
+ - run: pytest
31
+
32
+ build:
33
+ needs: test
34
+ runs-on: ubuntu-24.04
35
+ steps:
36
+ - uses: actions/checkout@v7
37
+ - uses: actions/setup-python@v7
38
+ with:
39
+ python-version: "3.12"
40
+ - name: Check release tag matches project version
41
+ env:
42
+ TAG: ${{ github.event.release.tag_name }}
43
+ run: |
44
+ version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
45
+ if [ "${TAG#v}" != "$version" ]; then
46
+ echo "::error::Release tag '$TAG' does not match pyproject version '$version'"
47
+ exit 1
48
+ fi
49
+ - run: python -m pip install build twine
50
+ - run: python -m build
51
+ - run: python -m twine check --strict dist/*
52
+ - uses: actions/upload-artifact@v7
53
+ with:
54
+ name: dist
55
+ path: dist/
56
+
57
+ publish:
58
+ needs: build
59
+ runs-on: ubuntu-24.04
60
+ environment:
61
+ name: pypi
62
+ url: https://pypi.org/project/snakevpn/
63
+ permissions:
64
+ id-token: write
65
+ steps:
66
+ - uses: actions/download-artifact@v8
67
+ with:
68
+ name: dist
69
+ path: dist/
70
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,8 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ .venv/
4
+ dist/
5
+ build/
6
+ .mypy_cache/
7
+ .pytest_cache/
8
+ .ruff_cache/
@@ -0,0 +1,110 @@
1
+ # AGENTS.md
2
+
3
+ Instructions for coding agents (Claude Code, Codex, Copilot, etc.) working in
4
+ this repository.
5
+
6
+ ## Project
7
+
8
+ pyvpn is **per-process policy routing** for the machine it runs on: it sends
9
+ each app's traffic (and its DNS) out through a chosen, already-existing
10
+ interface (`wg-jp`, `tun0`, `wlan1`, …), with fallback or a kill switch when
11
+ that interface is down. It does **not** create or manage VPN connections.
12
+
13
+ [PLAN.md](PLAN.md) is the source of truth for design, scope and milestones.
14
+ Read the relevant section before you change behaviour, and update PLAN.md in
15
+ the same change when a decision in it changes.
16
+
17
+ Key points from the plan:
18
+
19
+ - Distributed on PyPI as `snakevpn`; the import package and CLI are `pyvpn`.
20
+ - Python ≥ 3.11, `src/` layout, `pyproject.toml` with hatchling.
21
+ - **Linux only for now** (nft `socket cgroupv2` + fwmark + `ip rule`, via
22
+ `pyroute2`). macOS, Windows and proxy mode are deferred; don't build them
23
+ unless asked.
24
+ - Platform-specific code lives under `src/pyvpn/platform/linux/`, behind the
25
+ `Backend` protocol in `platform/base.py`. The shared core (config, rule
26
+ engine, DNS stubs, daemon, CLI) stays OS-agnostic so other OSes can be
27
+ added later.
28
+ - The root daemon stays small. The CLI and `pyvpn run` run unprivileged and
29
+ talk to the daemon over its unix socket.
30
+
31
+ This is a group project built in parallel. [WORKSTREAMS.md](WORKSTREAMS.md)
32
+ assigns each directory to a workstream. Stay inside your stream's
33
+ directories, code against the Phase 0 contracts (`state.py`,
34
+ `platform/base.py`, `daemon/api.py`, `config/models.py`, `constants.py`) and
35
+ the fakes in `tests/fakes/`, and do not change a contract without approval
36
+ from the streams that use it.
37
+
38
+ ## Working rules
39
+
40
+ - **Fail closed.** Any change to routing, nft rules or DNS must not open a
41
+ leak window. With `on_down: block`, traffic is dropped, never sent through
42
+ the default route.
43
+ - **Never touch the host network in unit tests.** Unit tests are pure (golden
44
+ nft JSON, fake netlink events, fake `/proc` trees). Anything that needs root
45
+ belongs in the namespace-based integration tests (PLAN.md §8).
46
+ - Do not run commands that change the developer's live routing, nft ruleset
47
+ or cgroups outside a throwaway network namespace.
48
+ - Keep changes scoped to the task; don't reformat unrelated code.
49
+
50
+ ## Tooling
51
+
52
+ Once the M0 scaffold exists (see PLAN.md §7):
53
+
54
+ ```bash
55
+ ruff check . && ruff format --check .
56
+ mypy src
57
+ pytest # unit tests, no root
58
+ sudo pytest -m integration # netns integration tests (Linux, root)
59
+ ```
60
+
61
+ Run lint, types and unit tests before committing.
62
+
63
+ ## Git and commits
64
+
65
+ - **Commit with the local git user account.** Use whatever `git config
66
+ user.name` / `user.email` resolve to in this checkout. Do **not**:
67
+ - set or change `user.name` / `user.email` (local or global config),
68
+ - pass `--author`, or set `GIT_AUTHOR_*` / `GIT_COMMITTER_*` env vars,
69
+ - commit as a bot or tool identity (e.g. `Claude <noreply@anthropic.com>`).
70
+
71
+ A `Co-Authored-By:` trailer for the agent is fine; the author and committer
72
+ must be the local user.
73
+ - Commit only when asked. Work on a branch, not directly on `main`.
74
+ - Write short, imperative commit subjects (e.g. `Plan: …`, `Add …`, `Fix …`).
75
+ - Never force-push or rewrite history that has been pushed without explicit
76
+ approval.
77
+
78
+ ## Branch names
79
+
80
+ Lowercase, words separated by `-`, no spaces. `<s>` is the workstream
81
+ letter from [WORKSTREAMS.md](WORKSTREAMS.md).
82
+
83
+ | Template | Use for | Example |
84
+ |---|---|---|
85
+ | `stream/<s>-<name>` | the one long-lived branch per workstream | `stream/b-daemon` |
86
+ | `feat/<s>-<topic>` | a new feature inside one workstream | `feat/d-gateway-discovery` |
87
+ | `fix/<s>-<topic>` | a bug fix inside one workstream | `fix/c-ipv6-masquerade` |
88
+ | `contracts/<topic>` | a change to a Phase 0 contract (needs approval from the streams that use it) | `contracts/destset-ports` |
89
+ | `ci/<topic>` | CI, tooling, release workflow | `ci/pin-ruff` |
90
+ | `docs/<topic>` | `PLAN.md`, `WORKSTREAMS.md`, `AGENTS.md`, README | `docs/branch-names` |
91
+
92
+ Long-lived stream branches:
93
+
94
+ | Stream | Branch |
95
+ |---|---|
96
+ | A config & CLI | `stream/a-cli` |
97
+ | B daemon | `stream/b-daemon` |
98
+ | C Linux routing & nft | `stream/c-routing` |
99
+ | D targets | `stream/d-targets` |
100
+ | E apps | `stream/e-apps` |
101
+ | F DNS & leaks | `stream/f-dns` |
102
+ | G rule engine | `stream/g-rules` |
103
+ | I test bed & CI | `stream/i-ci` |
104
+
105
+ - `feat/` and `fix/` branches start from their stream branch (or `main`)
106
+ and merge back into it; `contracts/`, `ci/` and `docs/` merge into `main`.
107
+ - Agents: branches created automatically by a tool (e.g. `claude/<random>`)
108
+ must be renamed to one of these templates before pushing.
109
+ - Delete a branch once it is merged; never delete another person's branch
110
+ without asking.