@decentnetwork/lan 0.1.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,197 @@
+# Configuring `@decentnetwork/lan`
+
+Everything decentlan needs is in **two YAML files** under
+`~/.agentnet/` (or whatever you pass to `--config-dir`):
+
+| file | what |
+|---|---|
+| `config.yaml` | Daemon-wide settings: this node's name, dora server(s), DNS domain/port, TUN interface, ACL files. |
+| `policy.yaml` | Optional per-peer ACL rules (allow / deny by port). Empty by default = trust the Carrier friend boundary. |
+
+See [`INSTALL.md`](INSTALL.md) for first-time setup.
+
+## `config.yaml` reference
+
+A full default config (what `agentnet init` writes):
+
+```yaml
+node:
+  name: my-laptop
+  namespace: agentnet-main
+
+carrier:
+  dataDir: /home/you/.agentnet/carrier
+  bootstrapNodes:
+    - { host: 47.100.103.201, port: 33445, pk: CX1XH419p4xJ5SV4KvDxBeKYSRdMJW9QpdWJY8owUxHd }
+    - { host: 154.64.235.176, port: 33445, pk: GdNtV2N74fZnLjhH7NhQ18nGdxb1k8jRM9dQaK7WnxmL }
+    # ... more
+  expressNodes:
+    - { host: lens.beagle.chat, port: 443, pk: ECbs4GxwGzxGerNkmqDJFibEmevu8jAXqAZtikccvD95 }
+
+network:
+  interface: agentnet0
+  ip: 10.86.1.10            # fallback if dora isn't reachable
+  subnet: 10.86.0.0/16
+  dnsDomain: decent
+  dnsPort: 5354
+
+paths:
+  ipamFile:   /home/you/.agentnet/ipam.yaml
+  policyFile: /home/you/.agentnet/policy.yaml
+  auditLog:   /home/you/.agentnet/audit.log
+
+proxy:
+  enabled: false             # `agentnet proxy enable` flips this
+  port: 8888
+
+friends:
+  autoAccept: true           # accept incoming friend-requests automatically
+
+dora:
+  enabled: false             # `agentnet dora enable --userid ...` flips this
+  userids: []                # tried in order; first responder wins
+  refreshIntervalMs: 60000
+```
+
+### `node`
+
+- **`name`** — your hostname inside the agentnet. Appears as
+  `<name>.<dnsDomain>` and in dora's roster. Must be unique per
+  dora.
+- **`namespace`** — informational. Same-namespace peers are
+  expected to share the same dora; not enforced.
+
+### `carrier`
+
+- **`dataDir`** — where the Carrier identity (`keypair.json`),
+  friend store, and Carrier-level metadata live. Treat this like
+  an SSH private key directory.
+- **`bootstrapNodes`** — fixed list of public Carrier DHT entry
+  points. The defaults shipped in the package work today; replace
+  if you're running a private bootstrap fleet.
+- **`expressNodes`** — HTTPS offline-message relays. Without one,
+  a friend-request sent while a peer is offline is lost.
+
+### `network`
+
+- **`interface`** — TUN device name on Linux. macOS uses kernel-
+  assigned `utun*` regardless of this field.
+- **`ip`** — fallback IP if dora can't be reached. **When dora is
+  enabled and reachable, dora's allocation overrides this.**
+- **`subnet`** — `/16` is the only tested size today. Don't change
+  unless you're running an isolated agentnet that won't talk to
+  any peers using the default.
+- **`dnsDomain`** — the suffix used by the in-process DNS server.
+  Default `decent`; legacy installs may have `agentnet`. Pick one
+  network-wide.
+- **`dnsPort`** — UDP port the DNS server tries first. Defaults to
+  5354 (5353 is held by `mDNSResponder` / Bonjour / `openclaw-
+  gateway` on most boxes). On EADDRINUSE the daemon falls back
+  upward (5354 → 5355 → ...). `agentnet dns install` reads the
+  actually-bound port via IPC and writes it into the OS resolver
+  config.
+
+### `proxy`
+
+Built-in HTTP-CONNECT proxy that listens on `<network.ip>:port`
+when `enabled: true`. Peers use it to proxy HTTPS through *this*
+node (e.g. accessing a SaaS API that geofences by source IP).
+ACL-gated; see `agentnet proxy --help`.
+
+### `friends`
+
+- **`autoAccept`** — accept incoming friend-requests automatically.
+  Carrier IS the trust boundary; if you don't want a peer, don't
+  share your address. Set to `false` for stricter networks; you'll
+  then need to run `agentnet friend-accept` manually for each one.
+
+### `dora`
+
+- **`enabled`** — turn on dora integration. When off, this node
+  uses `network.ip` directly and `paths.ipamFile` for peer lookups.
+- **`userids`** — list of dora servers to try, in order. First
+  responder wins.
+- **`refreshIntervalMs`** — how often to re-pull the roster from
+  dora (default 60s). Drives auto-friend discovery of new peers.
+
+## `policy.yaml` reference
+
+Empty by default — meaning every Carrier friend has full
+TCP / UDP access to this node's virtual IP. To tighten:
+
+```yaml
+defaultAction: deny
+rules:
+  - peer: wei.decent          # match by name OR carrier id
+    direction: inbound        # inbound | outbound | both
+    allow:
+      - { proto: tcp, port: 22, purpose: "ssh" }
+      - { proto: tcp, port: 18789, purpose: "openclaw" }
+    deny: []
+    expiresAt: 2026-05-09T23:59:00Z
+    audit: true
+  - peer: scratch.decent
+    direction: both
+    allow:
+      - { proto: any, port: 80 }
+      - { proto: any, port: 443 }
+```
+
+- `defaultAction` applies when no rule matches.
+- `direction` controls which side of the connection is checked:
+  `inbound` = packets from peer → us, `outbound` = us → peer,
+  `both` = both sides.
+- `expiresAt` is ISO 8601; expired rules are skipped at eval time
+  but kept in the file for audit.
+- `audit: true` logs every match (allowed or denied) to
+  `paths.auditLog`.
+
+ACL only applies to TCP/UDP packets (those have ports). ICMP is
+always allowed once IPAM lookup succeeds.
+
+CLI shortcuts:
+
+```bash
+agentnet grant --peer wei.decent --tcp 22 --tcp 18789 --expires 24h
+agentnet revoke --peer wei.decent
+agentnet audit log --tail 100
+```
+
+## Environment variables
+
+| var | effect |
+|---|---|
+| `AGENTNET_LOG_LEVEL` | `debug` / `info` / `warn` / `error`. Default `info`. |
+| `AGENTNET_HANDSHAKE_TIMEOUT_MS` | Packet-session handshake timeout. Default 30000. |
+| `DECENT_DEBUG=1` | Verbose Carrier SDK logs (very noisy; useful for connection debugging). |
+| `DECENT_EXPRESS_PULL_INTERVAL_MS` | Carrier express-relay poll interval. Default 4000. |
+
+## Operational commands
+
+```bash
+agentnet up [--real-tun] [--config-dir DIR]   # start daemon (foreground)
+agentnet down                                  # stop a backgrounded daemon
+agentnet status                                # human-readable status
+agentnet diag                                  # JSON dump (over IPC)
+agentnet identity show                         # this node's address + userid
+agentnet peers list                            # peers from IPAM
+agentnet resolve <name>                        # name → IP
+agentnet ipam assign --peer <id> --ip <ip> --name <name>
+agentnet friend-request --address <ADDRESS>    # (when daemon is up: routed via IPC)
+agentnet friends list
+agentnet grant / revoke                        # ACL shortcuts
+agentnet audit log [--tail N]
+agentnet dora enable --userid <ID>
+agentnet dora disable
+agentnet dora status
+agentnet dns install [--uninstall]
+agentnet dns hosts                             # /etc/hosts-format dump
+agentnet proxy { enable | disable | status | allow-host <H> | revoke-host <H> | list-hosts | use --peer <P> }
+```
+
+## See also
+
+- [`INSTALL.md`](INSTALL.md) — bootstrap, first-time setup
+- [`@decentnetwork/dora`](https://www.npmjs.com/package/@decentnetwork/dora) docs
+- [`@decentnetwork/peer`](https://www.npmjs.com/package/@decentnetwork/peer) docs
+- https://github.com/0xli/decentlan

package/docs/INSTALL.md

@@ -0,0 +1,145 @@
+# Installing `@decentnetwork/lan`
+
+`@decentnetwork/lan` is the client / daemon that joins a Decent
+AgentNet virtual LAN. It brings up a TUN interface, registers
+with a [dora](https://www.npmjs.com/package/@decentnetwork/dora) name
+server for an IP, and tunnels all `10.86.0.0/16` traffic to other
+peers over the [Carrier](https://www.npmjs.com/package/@decentnetwork/peer)
+peer-to-peer network. SSH, HTTP, and most TCP/UDP work
+transparently between any two daemons that are Carrier friends.
+
+## Requirements
+
+| | minimum |
+|---|---|
+| Node.js | **20+** |
+| OS | Linux (`x86_64`, `aarch64`) or macOS (`aarch64`, `x86_64`) |
+| Root / sudo | Yes — needed to create the TUN device. The daemon drops back to user-mode for everything else. |
+| Outbound network | TCP and UDP to public Carrier bootstrap nodes (ports 33445 + 443). No inbound port needed; no public IP needed. |
+
+Windows isn't supported yet; WSL2 with Linux mode works (UDP through
+WSL's NAT is unreliable, so the SDK falls back to TCP relay — works,
+just slower).
+
+## Install
+
+```bash
+npm install -g @decentnetwork/lan
+```
+
+This installs the `agentnet` CLI on `$PATH` along with platform-
+specific TUN helper binaries (we ship `linux-amd64`, `linux-arm64`,
+`darwin-amd64`, and `darwin-arm64`). Confirm:
+
+```bash
+agentnet --help
+```
+
+## First-time setup
+
+```bash
+# 1. Generate this machine's Carrier identity + default config
+agentnet init --name my-laptop
+
+# 2. (Once per network) friend the dora name server.
+#    Get the address from whoever runs dora.
+agentnet friend-request --address Jt7w1pKkyLT5GVue9h6ZPkjg1EeuuTbD6JVSLycXLsdm6nvBGSUd
+
+# 3. Tell decentlan to use that dora server
+agentnet dora enable --userid 98rsHv17h8G6AP9RagyrBiT1kmw4cn8MFPEembS6ZVjv
+
+# 4. Start the daemon (needs sudo for the TUN device)
+sudo $(which agentnet) up --real-tun
+```
+
+The daemon will:
+
+1. Open a Carrier connection
+2. Register with dora and get a virtual IP (e.g. `10.86.1.12`)
+3. Pull the network roster and auto-friend every other peer in it
+4. Bring up `agentnet0` on Linux (or `utun*` on macOS) at that IP
+5. Start a local DNS server for `*.decent` (default) so you can
+   `ping my-laptop.decent`, `ssh peer-name.decent`, etc.
+
+## OS DNS resolver (optional but recommended)
+
+Out-of-the-box you can resolve peers via `agentnet resolve <name>`
+or by IP. To make `ping <peer>.decent` work app-wide:
+
+```bash
+sudo $(which agentnet) dns install
+```
+
+- **macOS** — writes `/etc/resolver/<domain>` so the system
+  resolver routes `*.decent` queries to the daemon. Takes effect
+  immediately.
+- **Linux** — uses `resolvectl` to configure systemd-resolved
+  (when feasible). If your daemon is on a non-53 port (default
+  is 5354), the install command prints a `dnsmasq` snippet you can
+  paste; alternatively `agentnet dns hosts | sudo tee -a /etc/hosts`
+  gives you static name resolution without DNS at all.
+
+Reverse:
+
+```bash
+sudo $(which agentnet) dns install --uninstall
+```
+
+## Verify
+
+While the daemon is up (in another terminal — the daemon runs in
+foreground unless you background it yourself with `nohup`, systemd,
+etc.):
+
+```bash
+agentnet diag                  # JSON dump of state, friends, IPAM
+agentnet resolve <peer-name>   # IP from the live roster
+ping <peer-name>.decent        # if you ran 'dns install'
+```
+
+## Running the daemon as a service
+
+There's no built-in init script. Pattern is the same as any
+foreground binary; rough sketches:
+
+### systemd (Linux)
+
+```ini
+# /etc/systemd/system/agentnet.service
+[Unit]
+Description=Decent AgentNet daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/bin/agentnet up --real-tun --config-dir /home/<you>/.agentnet
+User=root
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### launchd (macOS)
+
+`/Library/LaunchDaemons/com.decent.agentnet.plist` — see
+`man launchd.plist`. Important: `Sudo` env isn't a thing in
+launchd, so put the daemon under `<key>UserName</key><string>root</string>`.
+
+## Uninstall
+
+```bash
+sudo $(which agentnet) up           # stop with Ctrl-C
+sudo $(which agentnet) dns install --uninstall
+npm uninstall -g @decentnetwork/lan
+rm -rf ~/.agentnet                  # delete identity + config (data loss)
+```
+
+## See also
+
+- [`CONFIGURATION.md`](CONFIGURATION.md) — full config.yaml reference,
+  ACL rules, proxy mode, debug logging.
+- [`@decentnetwork/dora`](https://www.npmjs.com/package/@decentnetwork/dora) —
+  the name server every daemon needs to talk to.
+- Project page: https://github.com/0xli/decentlan

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@decentnetwork/lan",
+  "version": "0.1.0",
+  "description": "Private virtual LAN for self-hosted services and AI agents, built on Elastos Carrier. NAT-traversal, name service, ACL, all over a peer-to-peer mesh — no public IP required.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "agentnet": "dist/cli/index.js",
+    "decentlan": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "docs/INSTALL.md",
+    "docs/CONFIGURATION.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "decent",
+    "decentnet",
+    "agentnet",
+    "vpn",
+    "p2p",
+    "carrier",
+    "nat-traversal",
+    "tun",
+    "virtual-lan",
+    "private-network",
+    "dora",
+    "ai-agents"
+  ],
+  "license": "GPL-3.0-or-later",
+  "author": "Decent Network contributors",
+  "homepage": "https://github.com/0xli/decentlan#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xli/decentlan.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0xli/decentlan/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:helper": "cd helper/tun-helper && go build -o ../../bin/tun-helper-$(go env GOOS)-$(go env GOARCH) .",
+    "build:helper:linux-amd64": "cd helper/tun-helper && GOOS=linux GOARCH=amd64 go build -o ../../bin/tun-helper-linux-amd64 .",
+    "build:helper:linux-arm64": "cd helper/tun-helper && GOOS=linux GOARCH=arm64 go build -o ../../bin/tun-helper-linux-arm64 .",
+    "build:helper:darwin-arm64": "cd helper/tun-helper && GOOS=darwin GOARCH=arm64 go build -o ../../bin/tun-helper-darwin-arm64 .",
+    "build:helper:darwin-amd64": "cd helper/tun-helper && GOOS=darwin GOARCH=amd64 go build -o ../../bin/tun-helper-darwin-amd64 .",
+    "build:helpers:all": "npm run build:helper:linux-amd64 && npm run build:helper:linux-arm64 && npm run build:helper:darwin-arm64 && npm run build:helper:darwin-amd64",
+    "build:all": "npm run build && npm run build:helper",
+    "clean": "rm -rf dist bin",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "rm -rf dist && npm run build && npm run typecheck && npm run build:helpers:all"
+  },
+  "dependencies": {
+    "@decentnetwork/dora": "^0.1.0",
+    "@decentnetwork/peer": "^0.1.0",
+    "js-yaml": "^4.1.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.12.12",
+    "@types/yargs": "^17.0.35",
+    "@typescript-eslint/eslint-plugin": "^7.10.0",
+    "@typescript-eslint/parser": "^7.10.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "eslint": "^8.57.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}