# 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