chore: snapshot before production push

2026-03-01 20:39:26 -05:00
commit 11b766c906
18 changed files with 1479 additions and 0 deletions
@@ -0,0 +1,55 @@
+# Darkproxy AI Coding Guidelines
+
+## Project Overview
+Darkproxy is a multi-container Docker stack enabling anonymous proxying across darknet (I2P, Tor) and clearnet. It chains SOCKS5 proxies through custom DNS resolvers, combining Yggdrasil networking, CoreDNS service orchestration, and blockchain-based TLD resolvers (Alfis, EmerCoin, meshname).
+
+## Architecture
+**Fixed container IPs on `darkproxy` network (10.5.0.0/16)**:
+- `10.5.0.2`: i2pd_yggdrasil - I2P + Yggdrasil IPv6 tunneling
+- `10.5.0.3`: alfis - Blockchain resolver for .anon/.ygg/.btn/.conf TLDs
+- `10.5.0.4`: coredns - CoreDNS (PopuraDNS) DNS orchestration hub
+- `10.5.0.5`: unbound - Recursive clearnet DNS
+- `10.5.0.6`: pihole - DNS filtering + upstream forwarder
+- `10.5.0.7`: tor_yggdrasil - Tor + Yggdrasil tunneling
+- `10.5.0.8`: dark3proxy - SOCKS5/HTTP proxy (main entrypoint)
+- `10.5.0.9`: emc - EmerCoin resolver for .emc/.coin/.lib domains
+
+**Data flow**: Client → dark3proxy (10.5.0.8:1080 SOCKS5) → pihole DNS (10.5.0.6) → coredns (10.5.0.4) → TLD-specific resolvers → upstream SOCKS backends (i2pd/tor).
+
+## Key Workflows
+**Build custom images** (with version pinning via build args):
+- I2P: `cd i2pd_yggdrasil_docker/src && ./make_docker_image.sh` (sets I2PD_VERSION=2.58.0, YGGDRASIL_VERSION=v0.5.12, UBUNTU_VERSION=24.04)
+- Tor: `cd tor_yggdrasil_docker && ./build_image.sh` (same versions via git describe fallback)
+- 3proxy: No build script—uses GitHub release binary download in Dockerfile
+
+**Deploy/Debug**:
+- Start: `docker-compose up --build` from root
+- Logs: `docker-compose logs -f coredns` (or dark3proxy, i2pd_yggdrasil, tor_yggdrasil)
+- Shell: `docker exec -it darkdns /bin/sh` (use container_name from compose)
+- Health: Each service has `healthcheck` or ping-based validation in entrypoint
+
+**Add new TLD resolver**:
+1. In docker-compose.yml: add new service with fixed IP in 10.5.0.x range, ensure internal network access
+2. In PopuraDNS/Corefile: add block like `newtld.:53 { acl { allow net 10.0.0.0/8 ...; block }; forward . 10.5.0.X:53 }`
+3. Rebuild coredns: `docker-compose up --build coredns`
+
+## Conventions
+**Secrets/Environment**: Stored in `secrets/` directory (tz.txt for timezone, YGGDRASIL_GENERATE_KEYS.txt for key generation). Mounted as Docker secrets, referenced in environment via `/run/secrets/`.
+
+**Proxy Routing Logic** (in `3proxy/first-instanse.cfg`):
+- Parent rules chain traffic: i2p domains → i2pd SOCKS (10.5.0.2:4447), onion → tor SOCKS (10.5.0.7:9050), Yggdrasil (200::/7) → local SOCKS, clearnet → tor fallback
+- Blacklist format: `{{vk.com,ok.ru,...}}` (blocks these domains)
+
+**DNS Stacking**: pihole (ad-filtering) → coredns (routing) → specialists. pihole upstreams to coredns (10.5.0.4), coredns forwards TLDs to resolvers. ACLs in Corefile block external networks; only 10.0.0.0/8, 127.0.0.1, fc00::/7 allowed.
+
+**Yggdrasil Key Generation**: Services `i2pd_yggdrasil` and `tor_yggdrasil` run Python utils (yggdrasil_get_keys, yggdrasil_find_public_peers) in entrypoint—generates strong keys + finds optimal peers unless YGGDRASIL_GENERATE_KEYS=false.
+
+**Networking**: All services require `sysctls: net.ipv6.conf.all.disable_ipv6=0` for Yggdrasil IPv6. Tunneling services (i2pd_yggdrasil, tor_yggdrasil) need `privileged: true`, `cap_add: NET_ADMIN`, `/dev/net/tun:/dev/net/tun`.
+
+## Examples
+- **Port Mapping** (via Yggdrasil IP 100.117.196.19): SOCKS on 2000→1080, 3proxy-eagle web 2002→8161, I2P console 2001→7070
+- **Config Mounting**: Read-only volumes for configs—e.g., `./unbound/unbound.conf:/opt/unbound/etc/unbound/unbound.conf`
+- **Image Tagging**: Custom builds tag as `service_name:${TAG_VERSION}` (git tag) and `:latest`; published to registry (host60/ prefix in docker-compose)
+
+Reference files: [docker-compose.yml](docker-compose.yml), [PopuraDNS/Corefile](PopuraDNS/Corefile), [3proxy/first-instanse.cfg](3proxy/first-instanse.cfg), [i2pd_yggdrasil_docker/src/make_docker_image.sh](i2pd_yggdrasil_docker/src/make_docker_image.sh), [tor_yggdrasil_docker/build_image.sh](tor_yggdrasil_docker/build_image.sh)</content>
+<parameter name="filePath">/home/sommopfle/darkproxy/.github/copilot-instructions.md
@@ -0,0 +1,63 @@
+name: "Configuration validation"
+
+on:
+  push:
+    paths:
+      - 'docker-compose.yml'
+      - 'PopuraDNS/**'
+      - '.github/workflows/**'
+  pull_request:
+    paths:
+      - 'docker-compose.yml'
+      - 'PopuraDNS/**'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Run full validation script
+        run: |
+          chmod +x scripts/validate-config.sh
+          scripts/validate-config.sh
+
+  smoke:
+    needs: lint
+    runs-on: ubuntu-latest
+    services:
+      docker:
+        image: docker:24-dind
+        privileged: true
+        options: >-
+          --cpus=2 --memory=4g
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Start stack and wait for health
+        run: |
+          docker compose up -d --build
+          # wait up to 120 seconds for each container's healthcheck to pass
+          for svc in darkdns darkpihole darkunbound darkalfis darkemer dark3proxy darktor darkproxy; do
+            echo "waiting for $svc"
+            for i in {1..24}; do
+              status=$(docker inspect -f '{{.State.Health.Status}}' $svc 2>/dev/null || echo none)
+              if [ "$status" = "healthy" ]; then
+                echo "$svc healthy" && break
+              fi
+              sleep 5
+            done
+          done
+          docker compose ps
+
+          # quick DNS smoke tests via CoreDNS container
+          echo "testing onion resolution"
+          docker exec darkdns dig +short @127.0.0.1 -p 53 facebookcorewwwi.onion
+          echo "testing i2p resolution"
+          docker exec darkdns dig +short @127.0.0.1 -p 53 stats.i2p
+
+          docker compose down