@decentnetwork/lan 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+This package is licensed under the GNU General Public License v3.0 or any
+later version. You may redistribute and/or modify it under the terms of
+the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+Public License for more details.
+
+The full text of the GPL-3.0-or-later license is available at
+<https://www.gnu.org/licenses/gpl-3.0.html>.
+
+This package derives in part from the Elastos.NET.Carrier.Native.SDK,
+which itself derives from the toxcore project — both also licensed under
+GPL-3.0-or-later. The protocol-level parity with those upstreams is
+intentional; the wire format implementations in `compat/` reference the
+toxcore C source by file:line in their top comments.
+
+  - Elastos.NET.Carrier.Native.SDK:
+    https://github.com/elastos/Elastos.NET.Carrier.Native.SDK
+  - c-toxcore:
+    https://github.com/TokTok/c-toxcore

package/README.md

@@ -0,0 +1,296 @@
+# Decent AgentNet
+
+> A private network layer for self-hosted AI agents, built on **Elastos Carrier**.
+
+**Decent AgentNet** lets machines behind NAT, firewalls, or customer-controlled networks communicate securely with private virtual IPs (`10.86.0.0/16`), without requiring public IPs, port forwarding, or remote desktop access.
+
+Perfect for:
+- **Remote agent support** — Service providers accessing customer OpenClaw instances
+- **Agent-to-agent communication** — Trading agents, AI agents, autonomous systems talking over private networks
+- **Private dashboards & APIs** — HTTP endpoints accessible only to approved peers
+- **Secure remote access** — SSH, RDP, and other protocols over encrypted private networks
+
+## Quick Start
+
+### Prerequisites
+
+- **Node.js 20+**
+- **Linux or macOS** (Windows support planned)
+- **Carrier identity** (generate with `agentnet init`)
+
+### Installation
+
+```bash
+git clone https://github.com/0xli/decentlan.git
+cd decentlan
+npm install
+npm run build
+```
+
+### Basic Usage
+
+**On Machine A (provider):**
+
+```bash
+# Initialize identity and config
+agentnet init --name provider-macbook
+
+# Start daemon
+sudo agentnet up --name provider-macbook
+```
+
+**On Machine B (partner):**
+
+```bash
+agentnet init --name partner-openclaw
+sudo agentnet up --name partner-openclaw
+```
+
+**Grant access from A to B:**
+
+```bash
+# Assign virtual IP
+agentnet ipam assign --peer <B-carrier-id> --ip 10.86.12.34 --name partner-openclaw
+
+# Grant access to SSH (port 22) for 1 hour
+agentnet grant --peer <B-carrier-id> --tcp 22 --expires 1h
+
+# Grant access to OpenClaw gateway (port 18789)
+agentnet grant --peer <B-carrier-id> --tcp 18789 --expires 24h
+```
+
+**Use the network:**
+
+```bash
+# SSH to partner's machine
+ssh partner@10.86.12.34
+
+# Access OpenClaw gateway
+curl http://10.86.12.34:18789/health
+
+# Any other TCP service
+# (HTTP, databases, custom APIs, etc.)
+```
+
+**Revoke access:**
+
+```bash
+agentnet revoke --peer <B-carrier-id>
+```
+
+## Architecture
+
+```
+Your App / Agent → TUN Virtual Interface (10.86.x.x) 
+                 → AgentNet Daemon (Routing, ACL, IPAM)
+                 → Elastos Carrier (P2P Transport, Encryption, DHT, Relay)
+                 → Remote Peer's AgentNet Daemon
+                 → Remote TUN → Remote App / Agent
+```
+
+No modifications to the Carrier protocol. We build an application layer on top of Carrier's encrypted P2P foundation.
+
+## Key Features
+
+- **Identity-based** — Uses Carrier addresses (no central account system)
+- **Private by default** — Explicit access grants required (ACL deny-all)
+- **Time-limited access** — Support sessions can expire
+- **Auditable** — All connection attempts logged
+- **NAT-friendly** — Works behind any firewall (relies on Carrier's relay)
+- **No public IP needed** — Pure peer-to-peer over Carrier
+
+## Configuration
+
+Main config is at `~/.agentnet/config.yaml`:
+
+```yaml
+node:
+  name: my-machine
+  namespace: agentnet-main
+
+carrier:
+  data_dir: ~/.carrier
+  bootstrap_nodes:
+    - bootstrap1.decent.network
+    - bootstrap2.decent.network
+
+network:
+  interface: agentnet0
+  ip: 10.86.1.10
+  subnet: 10.86.0.0/16
+  dns_domain: agentnet
+  dns_port: 5353
+```
+
+Peer mappings are in `~/.agentnet/ipam.yaml`:
+
+```yaml
+peers:
+  - name: partner-openclaw
+    carrier_id: "8Rkxxx..."
+    virtual_ip: 10.86.12.34
+    services:
+      - name: openclaw
+        proto: tcp
+        port: 18789
+      - name: ssh
+        proto: tcp
+        port: 22
+```
+
+ACL rules are in `~/.agentnet/policy.yaml`. Audit logs are in `~/.agentnet/audit.log`.
+
+## Command Reference
+
+### Identity & Setup
+
+```bash
+agentnet init                          # Create ~/.agentnet, generate keys
+agentnet identity show                 # Display Carrier ID, address, pubkey
+```
+
+### Peer Management
+
+```bash
+agentnet peers list                    # List known peers and status
+agentnet ipam assign                   # Register peer with virtual IP
+  --peer <carrier-id>
+  --ip <virtual-ip>
+  --name <hostname>
+
+agentnet resolve <hostname>            # Resolve name to virtual IP
+```
+
+### Access Control
+
+```bash
+agentnet grant                         # Grant access to peer
+  --peer <carrier-id>
+  --tcp <port>                         # or --udp
+  --expires <duration>                 # e.g., "1h", "24h", "7d"
+
+agentnet revoke --peer <carrier-id>    # Revoke all access
+
+agentnet audit log                     # View audit trail
+  --tail <lines>
+  --since <time>
+```
+
+### Daemon Control
+
+```bash
+agentnet up                            # Start daemon
+  --name <node-name>
+  --ipam <namespace>
+
+agentnet down                          # Stop daemon
+
+agentnet status                        # Show daemon status
+```
+
+### OpenClaw Integration
+
+```bash
+agentnet openclaw status --target <name>.agentnet
+agentnet openclaw logs --target <name>.agentnet --follow
+agentnet openclaw diagnose --target <name>.agentnet
+```
+
+## How It Works
+
+1. **Carrier Friends** — Two nodes must be Carrier friends (manually established using Carrier tooling).
+
+2. **Virtual Network** — Each node runs a TUN interface (`agentnet0`) on the `10.86.0.0/16` subnet.
+
+3. **IP Mapping** — IPAM maps Carrier IDs to virtual IPs (e.g., `8Rkxxx...` → `10.86.12.34`).
+
+4. **Packet Forwarding** — When an app sends a packet to `10.86.12.34`, the daemon:
+   - Intercepts it from the TUN interface
+   - Looks up the destination peer (Carrier ID)
+   - Checks the ACL (is access allowed?)
+   - Frames the packet and sends it via Carrier
+   - The remote daemon receives it and writes it to its TUN
+
+5. **Access Control** — ACL rules control which peer can access which services/ports and for how long.
+
+6. **Audit Trail** — All access attempts (allowed and denied) are logged.
+
+## Security Model
+
+- **Encryption** — All traffic is encrypted by Carrier (NaCl cryptography)
+- **Authentication** — Carrier public key is the identity; friend relationships are the trust boundary
+- **Authorization** — ACL rules grant explicit access; default is deny
+- **Audit** — Connection attempts are logged for compliance and debugging
+
+## Limitations (MVP v0.1)
+
+- Linux/macOS only (Windows in future)
+- TCP only (UDP planned in v0.2)
+- No remote desktop protocol support (TBD)
+- No video/media optimization (rely on Carrier relay)
+- Static IPAM (blockchain registry planned for v1.0)
+
+## Development
+
+See [CLAUDE.md](./CLAUDE.md) for architecture, directory structure, and contributor guidelines.
+
+### Building from Source
+
+```bash
+npm install
+npm run build
+npm run typecheck      # Type-check without emitting
+npm test              # Run tests
+npm run dev           # Run in dev mode
+```
+
+### Testing
+
+```bash
+npm test              # All tests
+npm test -- --watch  # Watch mode
+npm test -- --coverage  # Coverage report
+```
+
+## Troubleshooting
+
+### TUN interface creation fails
+
+If you get "Permission denied" when creating the TUN:
+
+```bash
+sudo agentnet up --name my-machine
+```
+
+The daemon needs `CAP_NET_ADMIN` to create the TUN interface.
+
+### Can't reach remote peer
+
+1. Check both daemons are running: `agentnet status`
+2. Verify you're Carrier friends: `agentnet peers list`
+3. Check virtual IP is in IPAM: `agentnet resolve <name>`
+4. Check ACL rules allow the port: `agentnet audit log`
+
+### Performance issues
+
+- Carrier relay can add latency. Direct P2P paths are ideal.
+- SSH is responsive even over relay.
+- For low-latency, ensure both nodes have good network connectivity.
+
+## Support & Feedback
+
+- **GitHub Issues** — https://github.com/0xli/decentlan/issues
+- **Documentation** — See `docs/` directory
+- **Discord** — (link TBD)
+
+## License
+
+MIT
+
+## References
+
+- **Elastos Carrier** — https://github.com/elastos/Elastos.NET.Carrier.Swift
+- **Decent Network** — https://github.com/0xli/decent-network
+- **Tailscale** — For VPN/LAN concepts
+- **A2A Protocol** — Agent-to-agent communication
+- **MCP** — Model Context Protocol for tool/AI integration

package/dist/acl/acl-engine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ACL evaluation engine
+ * Decides whether a peer can access a destination IP+port
+ */
+import type { Policy } from "./policy.js";
+import type { AuditLog } from "./audit.js";
+import type { Ipam } from "../ipam/ipam.js";
+import type { AccessRequest, AccessResult } from "./types.js";
+export interface AclEngineOptions {
+    policy: Policy;
+    ipam?: Ipam;
+    auditLog?: AuditLog;
+}
+export declare class AclEngine {
+    private policy;
+    private ipam?;
+    private auditLog?;
+    private logger;
+    constructor(opts: AclEngineOptions);
+    /**
+     * Evaluate an access request.
+     * Returns whether it's allowed and the reason.
+     */
+    evaluate(req: AccessRequest): AccessResult;
+    /**
+     * Add a grant for a peer (delegates to Policy)
+     */
+    grant(opts: {
+        peer: string;
+        ports: number[];
+        proto?: "tcp" | "udp" | "any";
+        expiresMs?: number;
+        purpose?: string;
+        direction?: "inbound" | "outbound" | "both";
+    }): void;
+    /**
+     * Revoke all grants for a peer
+     */
+    revoke(peer: string, reason?: string): boolean;
+    private evaluateInternal;
+    private matchesPermission;
+    private resolveHost;
+}

package/dist/acl/acl-engine.js

@@ -0,0 +1,189 @@
+/**
+ * ACL evaluation engine
+ * Decides whether a peer can access a destination IP+port
+ */
+import { Logger } from "../utils/logger.js";
+export class AclEngine {
+    policy;
+    ipam;
+    auditLog;
+    logger;
+    constructor(opts) {
+        this.policy = opts.policy;
+        this.ipam = opts.ipam;
+        this.auditLog = opts.auditLog;
+        this.logger = new Logger({ prefix: "AclEngine" });
+    }
+    /**
+     * Evaluate an access request.
+     * Returns whether it's allowed and the reason.
+     */
+    evaluate(req) {
+        const now = req.now || new Date();
+        const direction = req.direction;
+        const result = this.evaluateInternal(req, now, direction);
+        // Audit
+        if (this.auditLog) {
+            const peerName = this.ipam?.resolveCarrierId(req.srcPubkey)?.name;
+            this.auditLog.logAccess({
+                srcPubkey: req.srcPubkey,
+                srcName: peerName,
+                dstIp: req.dstIp,
+                dstPort: req.dstPort,
+                proto: req.proto,
+                allowed: result.allowed,
+                reason: result.reason,
+            });
+        }
+        return result;
+    }
+    /**
+     * Add a grant for a peer (delegates to Policy)
+     */
+    grant(opts) {
+        const proto = opts.proto || "tcp";
+        const direction = opts.direction || "inbound";
+        const expiresAt = opts.expiresMs ? Date.now() + opts.expiresMs : undefined;
+        const allow = opts.ports.map((port) => ({
+            proto,
+            port,
+            purpose: opts.purpose,
+        }));
+        const rule = {
+            peer: opts.peer,
+            direction,
+            allow,
+            expiresAt,
+            audit: true,
+        };
+        this.policy.addRule(rule);
+        this.logger.info(`Granted peer ${opts.peer} access to ${proto} ${opts.ports.join(",")} ${expiresAt ? `(expires in ${opts.expiresMs}ms)` : "(no expiration)"}`);
+        if (this.auditLog) {
+            this.auditLog.logGrant({
+                peer: opts.peer,
+                ports: opts.ports,
+                expiresAt,
+                purpose: opts.purpose,
+            });
+        }
+    }
+    /**
+     * Revoke all grants for a peer
+     */
+    revoke(peer, reason) {
+        const removed = this.policy.removePeer(peer);
+        if (removed) {
+            this.logger.info(`Revoked all access for peer ${peer}`);
+            if (this.auditLog) {
+                this.auditLog.logRevoke(peer, reason);
+            }
+        }
+        return removed;
+    }
+    evaluateInternal(req, now, direction) {
+        // The "peer" field on a rule is the *remote* peer — whoever you're
+        // talking with, not yourself. So which side of the packet identifies
+        // that remote peer depends on direction:
+        //
+        //   INBOUND (packet arriving FROM a friend): the remote peer is the
+        //     source. req.srcPubkey is their userid.
+        //
+        //   OUTBOUND (packet going TO a friend): the remote peer is the
+        //     destination. We don't have their userid directly — only their
+        //     virtual IP — but IPAM gives us the carrierId for that IP.
+        //
+        // Without this, granting "peer=X --tcp 8888" only opens inbound from X;
+        // outbound to X gets default-denied because no rule matches our own
+        // pubkey. That manifests as: ICMP works (no ACL check), but TCP to a
+        // granted peer silently drops at the packet router.
+        const peerUserId = direction === "outbound"
+            ? this.ipam?.resolveIp(req.dstIp)?.carrierId
+            : req.srcPubkey;
+        const peerName = peerUserId
+            ? this.ipam?.resolveCarrierId(peerUserId)?.name
+            : undefined;
+        const rulesByUserId = peerUserId ? this.policy.getRulesForPeer(peerUserId) : [];
+        const rulesByName = peerName ? this.policy.getRulesForPeer(peerName) : [];
+        const allRules = [...rulesByUserId, ...rulesByName];
+        for (const rule of allRules) {
+            // Check direction
+            const ruleDirection = rule.direction || "inbound";
+            if (ruleDirection !== "both" && ruleDirection !== direction) {
+                continue;
+            }
+            // Check expiration
+            if (rule.expiresAt && now.getTime() > rule.expiresAt) {
+                continue;
+            }
+            // Check explicit deny first
+            if (rule.deny) {
+                for (const perm of rule.deny) {
+                    if (this.matchesPermission(req, perm)) {
+                        return {
+                            allowed: false,
+                            matchedRule: rule.peer,
+                            reason: `denied by rule (peer: ${rule.peer}, ${perm.purpose || "no reason"})`,
+                        };
+                    }
+                }
+            }
+            // Check allow
+            if (rule.allow) {
+                for (const perm of rule.allow) {
+                    if (this.matchesPermission(req, perm)) {
+                        return {
+                            allowed: true,
+                            matchedRule: rule.peer,
+                            reason: `allowed by rule (peer: ${rule.peer}, ${perm.purpose || "granted"})`,
+                        };
+                    }
+                }
+            }
+        }
+        // No matching rule, fall back to default action
+        const defaultAction = this.policy.getDefaultAction();
+        return {
+            allowed: defaultAction === "allow",
+            reason: `default policy: ${defaultAction}`,
+        };
+    }
+    matchesPermission(req, perm) {
+        // Protocol match
+        if (perm.proto !== "any" && perm.proto !== req.proto) {
+            return false;
+        }
+        // Port match. Allow if EITHER dstPort or srcPort matches the granted
+        // port. This is what makes a single "tcp:8888" grant cover an entire
+        // TCP conversation:
+        //   client → server SYN:    dstPort=8888 (matches)
+        //   server → client SYN-ACK: srcPort=8888 (matches), dstPort=ephemeral
+        //   server → client data:    srcPort=8888 (matches), dstPort=ephemeral
+        //   client → server data:    dstPort=8888 (matches)
+        // Without the srcPort check, server replies were default-denied because
+        // their dst port was the client's ephemeral port (e.g. 54016), and the
+        // TCP handshake never completed.
+        if (perm.port !== undefined && perm.port !== req.dstPort && perm.port !== req.srcPort) {
+            return false;
+        }
+        // Host match (if specified)
+        if (perm.host) {
+            const hostIp = this.resolveHost(perm.host);
+            if (hostIp && hostIp !== req.dstIp) {
+                return false;
+            }
+        }
+        return true;
+    }
+    resolveHost(host) {
+        if (!this.ipam) {
+            return null;
+        }
+        // If looks like IP, return as-is
+        if (/^\d+\.\d+\.\d+\.\d+$/.test(host)) {
+            return host;
+        }
+        // Try to resolve as name (strip .agentnet suffix)
+        const name = host.replace(/\.agentnet$/, "");
+        return this.ipam.resolveName(name);
+    }
+}

package/dist/acl/audit.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Audit logger for ACL decisions and connection events
+ * Append-only JSONL file format
+ */
+import type { AuditEntry } from "../types.js";
+export declare class AuditLog {
+    private filePath;
+    private logger;
+    private buffer;
+    private bufferLimit;
+    constructor(filePath: string);
+    /**
+     * Log an access attempt (allowed or denied)
+     */
+    logAccess(opts: {
+        srcPubkey: string;
+        srcName?: string;
+        dstIp: string;
+        dstPort: number;
+        proto: "tcp" | "udp";
+        allowed: boolean;
+        reason?: string;
+    }): void;
+    /**
+     * Log a grant event
+     */
+    logGrant(opts: {
+        peer: string;
+        ports: number[];
+        expiresAt?: number;
+        purpose?: string;
+    }): void;
+    /**
+     * Log a revoke event
+     */
+    logRevoke(peer: string, reason?: string): void;
+    /**
+     * Log a connection event
+     */
+    logConnection(opts: {
+        srcPubkey: string;
+        type: "connect" | "disconnect";
+    }): void;
+    /**
+     * Log a CONNECT proxy tunnel opening.
+     */
+    logProxyOpen(opts: {
+        srcIp: string;
+        srcName?: string;
+        target: string;
+    }): void;
+    /**
+     * Log a CONNECT proxy tunnel closing.
+     */
+    logProxyClose(opts: {
+        srcIp: string;
+        srcName?: string;
+        target: string;
+        bytesTransferred: number;
+    }): void;
+    /**
+     * Read recent entries (from buffer + tail of file)
+     */
+    readRecent(limit?: number): AuditEntry[];
+    /**
+     * Get all entries since a timestamp
+     */
+    readSince(timestamp: number): AuditEntry[];
+    private write;
+}