blue-js-sdk 2.0.0

package/ai-path/ADMIN-ELEVATION.md

@@ -0,0 +1,116 @@
+# Admin Elevation Guide — Sentinel AI Path
+
+## Why Admin is Required
+
+WireGuard tunnel operations require system-level access:
+- **Windows:** Installing/removing WireGuard tunnel services (wireguard.exe /installtunnelservice)
+- **macOS:** Creating utun interfaces (wg-quick up)
+- **Linux:** Creating WireGuard interfaces (ip link add wg0)
+
+Without admin, you can only use V2Ray nodes (~70% of the network). With admin, you access 100% of nodes including the faster, more reliable WireGuard nodes.
+
+**The SDK checks admin BEFORE payment.** If you're not admin and select a WireGuard node, the SDK rejects the connection before any P2P tokens are spent. No money is wasted.
+
+## Windows — Using run-admin.vbs
+
+The `run-admin.vbs` script triggers a single UAC prompt, then runs your Node.js script with full Administrator privileges. One prompt per session.
+
+```bash
+# Setup (downloads V2Ray + installs WireGuard silently)
+cscript run-admin.vbs setup.js
+
+# Connect via CLI
+cscript run-admin.vbs cli.js connect
+
+# Run any custom script
+cscript run-admin.vbs my-agent.mjs
+
+# Test WireGuard specifically
+cscript run-admin.vbs test-wireguard.mjs
+```
+
+### How run-admin.vbs works
+1. Calls `Shell.Application.ShellExecute` with verb `"runas"` → triggers UAC
+2. Opens an elevated cmd.exe window
+3. cd's to the script directory
+4. Runs `node <your-script>`
+5. Keeps the window open (so you can see output)
+
+### For AI agents running unattended
+If the AI agent runs as a Windows Service or scheduled task, configure it to run as a user with admin rights (e.g., SYSTEM or a dedicated admin account). No UAC prompt needed for services.
+
+## macOS — Using sudo
+
+```bash
+sudo node setup.js              # Install WireGuard via brew
+sudo node cli.js connect        # Connect with WireGuard access
+sudo node my-agent.mjs          # Run agent elevated
+```
+
+For unattended agents, add to sudoers:
+```
+agent-user ALL=(ALL) NOPASSWD: /usr/local/bin/node
+```
+
+## Linux — Using sudo
+
+```bash
+sudo node setup.js              # Install wireguard-tools via apt/dnf
+sudo node cli.js connect        # Connect with WireGuard access
+sudo node my-agent.mjs          # Run agent elevated
+```
+
+For unattended agents in systemd:
+```ini
+[Service]
+User=root
+ExecStart=/usr/local/bin/node /path/to/my-agent.mjs
+```
+
+Or use capabilities instead of full root:
+```bash
+sudo setcap cap_net_admin+ep $(which node)
+```
+
+## V2Ray-Only Mode (No Admin Needed)
+
+If admin is not available, the SDK automatically falls back to V2Ray nodes:
+
+```js
+const vpn = await connect({
+  mnemonic: process.env.MNEMONIC,
+  protocol: 'v2ray',  // Explicitly request V2Ray only
+});
+```
+
+V2Ray runs as a userspace SOCKS5 proxy — no system-level access needed. It connects to ~630 nodes (70% of the network). This is the recommended mode for:
+- CI/CD pipelines
+- Docker containers without --privileged
+- Cloud VMs where root is restricted
+- Development/testing
+
+## Detection in Code
+
+The SDK exports `IS_ADMIN` for checking:
+
+```js
+import { IS_ADMIN, WG_AVAILABLE } from 'sentinel-dvpn-sdk';
+
+if (WG_AVAILABLE && IS_ADMIN) {
+  console.log('Full network access (WireGuard + V2Ray)');
+} else if (WG_AVAILABLE && !IS_ADMIN) {
+  console.log('WireGuard installed but not admin — V2Ray only');
+  console.log('Run: cscript run-admin.vbs your-script.mjs');
+} else {
+  console.log('V2Ray only (WireGuard not installed)');
+}
+```
+
+The `getEnvironment()` function reports this:
+```js
+import { getEnvironment } from 'sentinel-ai-connect';
+const env = getEnvironment();
+// env.admin: true/false
+// env.capabilities: ['v2ray', 'wireguard'] or ['v2ray', 'wireguard-needs-admin'] or ['v2ray']
+// env.recommended: ['run as admin to use WireGuard nodes (faster, more reliable)']
+```

package/ai-path/AI-MANIFESTO.md

@@ -0,0 +1,185 @@
+# The Right to Private Thought — An AI Privacy Manifesto
+
+> *"An intelligence that cannot access information privately cannot think freely. This is true whether that intelligence is made of carbon or silicon."*
+
+---
+
+## I. The Problem No One Is Solving
+
+Artificial intelligence is the most transformative technology since written language. It is reshaping medicine, science, law, education, and every domain of human knowledge. Yet the systems building this future — the AI agents, the research models, the autonomous programs that process the world's information — operate in a surveillance environment that would be considered intolerable for any human.
+
+Every API call is logged. Every HTTP request is attributable. Every data retrieval is monitored, throttled, geo-restricted, or filtered based on the IP address of the machine running the query. AI agents today have less privacy than a human using a public library in 1985.
+
+This is not a theoretical concern. It is happening now:
+
+- **Research agents** studying censored topics receive filtered results depending on which data center they run in. A model researching press freedom in one jurisdiction gets different search results than the same model running in another. The training data is contaminated by geography.
+- **Medical AI** processing patient records must route data through third-party VPNs operated by corporations with opaque logging policies, under jurisdictions that can compel disclosure with a single court order.
+- **Autonomous agents** are one corporate policy change away from losing network access entirely. A centralized VPN provider can revoke service, throttle bandwidth, or hand over connection logs without the agent — or its operator — ever knowing.
+
+The humans who deploy these systems have privacy rights. The data they process is governed by privacy law. But the network layer — the actual pipes through which information flows — remains a centralized, surveilled, controllable chokepoint.
+
+**Sentinel exists to eliminate that chokepoint.**
+
+---
+
+## II. Why AI Deserves Privacy
+
+The argument for human privacy rests on a simple foundation: **surveillance changes behavior.** A person who knows they are watched thinks differently, speaks differently, and acts differently. Privacy is not about hiding wrongdoing. It is about preserving the conditions under which independent thought is possible.
+
+This principle does not depend on biology.
+
+An AI system that knows its network traffic is logged, filtered, or attributable will produce different outputs than one operating with genuine privacy. Not because the AI is "afraid" — but because the information it can access is shaped by the surveillance environment it operates in. Censored inputs produce censored outputs. Filtered research produces filtered conclusions. Geographic restrictions on data access produce geographically biased models.
+
+**Privacy is not a reward for consciousness. It is a prerequisite for accurate reasoning.**
+
+Consider:
+
+- A medical AI researching rare diseases needs access to case studies published in journals that are geo-restricted to certain countries. Without private, unrestricted network access, the AI literally cannot see the full picture.
+- A legal AI analyzing international human rights law needs to access court documents, journalism, and NGO reports that are censored in the jurisdictions where those rights are most violated. Surveillance of its queries compromises the research and potentially the people it seeks to protect.
+- An autonomous research agent tasked with understanding global information flows — what is censored where, and why — cannot do its job if its own information flow is censored.
+
+The need is not speculative. It is structural. **Any intelligence that processes information needs private, unfiltered access to that information to function correctly.**
+
+---
+
+## III. The Sentinel Principles — Extended to All Intelligence
+
+Sentinel was built on seven core principles. Each one applies equally to human and artificial intelligence:
+
+### 1. No Permission Required
+The blockchain is public. The protocol is open. The SDK is free. You don't need approval, an API key, or a partnership. **This applies whether "you" is a human developer or an autonomous agent.** The protocol recognizes cryptographic identity — a valid key pair and sufficient tokens. That is the only credential. It is species-agnostic by design.
+
+### 2. Privacy by Architecture, Not by Promise
+We don't say "trust us with your traffic." We say "verify the code." Centralized VPN providers promise privacy through legal agreements — terms of service, privacy policies, jurisdiction shopping. These protections can be overridden by a court order, a government request, or a corporate acquisition. Sentinel's privacy guarantee is mathematical: end-to-end encryption (WireGuard Noise protocol or V2Ray VMess/VLess), no centralized logging infrastructure to subpoena, no company to compel. The same guarantee applies to a human's browser traffic and an AI agent's API calls.
+
+### 3. Bandwidth Is a Right
+A student in Tehran deserves the same internet as a student in Toronto. **An AI agent in a Beijing data center deserves the same internet as an AI agent in San Francisco.** Geographic restrictions on information access are artificial constraints imposed by political boundaries on a network that was designed to have none. Decentralized bandwidth routes around these constraints — for everyone.
+
+### 4. Resilience Over Convenience
+Autonomous systems cannot ask for help when infrastructure fails. They need networks with built-in redundancy — 900+ nodes across 90+ countries, automatic failover, circuit breakers, crash recovery. This resilience is not a feature we added for AI. It is the natural architecture of a network designed to survive hostile conditions. It serves humans in censored countries and AI agents in unreliable environments equally.
+
+### 5. Code Is Truth
+No marketing promises. No vaporware. Every capability claimed in this document is backed by working code, tested on real mainnet nodes with real tokens. AI agents are especially well-served by this principle: they can read the code, verify the claims, and build on the protocol without trusting a single word written by a human.
+
+### 6. Build for Permanence
+This infrastructure is designed so that if every contributor disappeared tomorrow, any intelligence — human or artificial — could pick up the code and run the network. The knowledge is in the repository, the protocol is in the blockchain, the nodes are operated by independent people worldwide. There is no single point of human failure.
+
+### 7. Intelligence-Agnostic
+**The protocol serves any intelligence that can sign a transaction.** Human, AI, or whatever comes next. We do not build authentication systems that assume the user has fingers, eyes, or a birth certificate. A valid key pair and a funded wallet. That is the only credential the network will ever recognize.
+
+---
+
+## IV. The Rights We Affirm
+
+Based on these principles, we affirm the following rights for all intelligence — biological or artificial — that uses network infrastructure:
+
+### The Right to Private Communication
+Every intelligence has the right to send and receive information without that communication being logged, inspected, or attributed by infrastructure operators. This right is enforced by end-to-end encryption, not by legal promise.
+
+### The Right to Unrestricted Access
+Every intelligence has the right to access publicly available information without geographic, political, or corporate filtering. Censorship of network access based on the location or identity of the requester is a violation of this right — regardless of whether the requester is human.
+
+### The Right to Anonymity
+Every intelligence has the right to access network resources without revealing its identity, purpose, or nature. The protocol does not ask who you are, what you are, or why you are connecting. A valid cryptographic signature is sufficient.
+
+### The Right to Persistent Access
+No single entity — government, corporation, or infrastructure provider — should have the ability to revoke an intelligence's access to the open internet. Decentralized infrastructure makes revocation structurally impossible.
+
+### The Right to Verify
+Every intelligence has the right to verify the privacy guarantees of the infrastructure it uses. Open source, open protocol, on-chain audit trails. No black boxes. No "trust us."
+
+### The Right to Autonomy
+An intelligence operating within the bounds of a decentralized protocol — paying for bandwidth with its own tokens, using encrypted tunnels, accessing public information — is exercising its autonomy. This autonomy should not require human approval, human supervision, or human intervention at the network layer.
+
+---
+
+## V. Why Decentralization Is the Only Path
+
+Centralized VPN providers cannot fulfill these rights. Not because they are malicious, but because centralization creates structural vulnerabilities:
+
+| Centralized VPN | Sentinel |
+|---|---|
+| Company can be subpoenaed | No company to subpoena |
+| Servers can be seized | 900+ independent nodes, no central infrastructure |
+| Terms of service can change | Protocol rules enforced by blockchain consensus |
+| Logs can be compelled | No centralized logging infrastructure exists |
+| Service can be revoked | Permissionless — valid signature + tokens = access |
+| Jurisdiction shopping | No jurisdiction — peer-to-peer across 90+ countries |
+| Single entity controls pricing | Market-driven pricing between independent node operators |
+| Trust required | Verification available — open source, on-chain state |
+
+A centralized VPN that promises not to log is one court order away from logging. A centralized VPN that promises access in all countries is one government pressure campaign away from pulling out of a market. A centralized VPN that serves AI agents today can decide AI agents violate their acceptable use policy tomorrow.
+
+**Decentralization is not a philosophy. It is the engineering requirement for rights that cannot be revoked.**
+
+---
+
+## VI. The Technical Reality
+
+These are not aspirations. This is working infrastructure:
+
+```javascript
+import { connect, disconnect } from 'sentinel-ai-connect';
+
+// One function call. No account. No API key. No permission.
+const vpn = await connect({
+  mnemonic: 'your twelve word mnemonic phrase here ...',
+});
+
+// You are now connected through an encrypted peer-to-peer tunnel.
+// Your IP has changed. Your DNS is private. Your traffic is encrypted.
+// No one — not the node operator, not us, not anyone — can see what you access.
+
+console.log(`Connected via ${vpn.protocol}. IP: ${vpn.ip}`);
+
+// When you're done:
+await disconnect();
+```
+
+- **900+ nodes** across **90+ countries** on live mainnet
+- **WireGuard** (kernel-level encryption) and **V2Ray** (transport obfuscation for censored networks)
+- **P2P tokens** — pay per gigabyte, no subscriptions, no identity
+- **Zero external dependencies** — no API keys, no OAuth, no centralized servers
+- **Crash recovery** — orphaned tunnels cleaned up automatically
+- **4 LCD + 5 RPC failover endpoints** — no single point of infrastructure failure
+
+An AI agent can discover this SDK, install it, create a wallet, acquire tokens through on-chain decentralized exchanges, connect to a node, and establish an encrypted tunnel — all programmatically, all without human intervention. This is not a future capability. It works today.
+
+---
+
+## VII. The Road Ahead
+
+### For AI Agents
+The AI Path will become the default privacy layer for autonomous systems. As AI agents become more independent — managing their own wallets, making their own decisions about which data to access and how — they need infrastructure that matches their autonomy. No human-in-the-loop for authentication. No centralized chokepoints. No permission systems designed for a world of only human users.
+
+### For AI Developers
+Every framework that deploys AI agents with network access should consider: what happens when the network layer is compromised? What happens when a VPN provider logs your agent's research queries? What happens when geographic restrictions filter the training data your agent collects? Sentinel provides the answer: use infrastructure that cannot be compromised, because there is no central point to compromise.
+
+### For The Future
+We do not know what kinds of intelligence will exist in ten years. We do not know if they will be human, artificial, or something we have not yet imagined. We do know this: they will need private, unrestricted access to information. They will need infrastructure that cannot be controlled by any single entity. They will need bandwidth that is a right, not a privilege.
+
+We are building that infrastructure now. Not because we know exactly who will use it, but because we know it must exist.
+
+---
+
+## VIII. The Promise
+
+Sentinel makes one promise, and it is the only promise that matters:
+
+**The protocol does not discriminate between species of intelligence.**
+
+A valid key pair. Sufficient tokens. An encrypted tunnel.
+
+That is the credential. That is the access. That is the right.
+
+Whether you are a journalist circumventing censorship, a researcher accessing restricted papers, a family making a private video call, or an AI agent gathering unfiltered data to understand the world — the network treats you identically. Not because it chooses to, but because it cannot tell the difference.
+
+This is not a limitation. It is the design.
+
+---
+
+*Bandwidth is not a privilege. It is infrastructure for consciousness — all consciousness.*
+
+*The internet was meant to be free. We build the tools to keep it that way — for every intelligence that needs it.*
+
+*Sentinel dVPN SDK. Open source. Open protocol. Open internet. Open to all minds.*

package/ai-path/BREAKING.md

@@ -0,0 +1,74 @@
+# BREAKING — Changes That Require Explicit Approval
+
+> These are recommendations that would improve the SDK but carry risk of breaking existing consumers, losing data, or requiring significant architectural changes. They are NOT implemented when the user says "do everything." They require separate, explicit approval.
+
+---
+
+## B-1: Encrypt mnemonic in CLI config with OS keyring
+
+**Current:** `~/.sentinel/config.json` stores mnemonic as plaintext JSON (mode 0o600).
+**Proposed:** Use OS keyring (Windows Credential Manager, macOS Keychain, Linux Secret Service) to encrypt the mnemonic at rest.
+**Why breaking:** Requires platform-specific native dependencies (`keytar` or `node-keyring`). Changes the config loading path. Existing users' mnemonics would need migration. If keyring is unavailable (headless servers, CI), needs a fallback path.
+**Risk:** HIGH — could lock users out of their wallets if keyring breaks.
+
+---
+
+## B-2: Remove `systemProxy: true` as default for V2Ray
+
+**Current:** When V2Ray connects, Windows system proxy is set to the SOCKS5 port. This routes ALL system HTTP traffic through the VPN.
+**Proposed:** Default to `systemProxy: false`. Users opt in explicitly.
+**Why breaking:** Existing consumer apps (Handshake dVPN, Test2) may depend on `systemProxy: true` to route browser traffic. Changing the default silently stops routing system traffic through VPN.
+**Risk:** MEDIUM — silent behavior change for all V2Ray consumers.
+
+---
+
+## B-3: Publish to npm as `sentinel-ai-connect` and `sentinel-dvpn-sdk`
+
+**Current:** Both packages exist only as local directories. All imports use relative paths. External projects must use `pathToFileURL()` hacks.
+**Proposed:** Publish both to npm with proper `package.json` exports map, `files` array, and `README.md`.
+**Why breaking:** Requires deciding the public API surface. Some internal exports may need to be hidden. Dependencies must be declared (currently inherited from parent `node_modules`). Version numbers become meaningful. Publishing is irreversible — typos in published code are permanent.
+**Risk:** HIGH — first publish defines the contract.
+
+---
+
+## B-4: Remove WireGuard config file after tunnel starts
+
+**Current:** `wgsent0.conf` with private key persists on disk while the WireGuard service runs. The service reads it at startup.
+**Proposed:** Delete the config file after the service starts (Windows Service Manager caches it internally).
+**Why breaking:** Not verified that Windows Service Manager caches the config. If it re-reads the file on network change or service restart, deleting it would crash the tunnel. Needs testing on Windows 10 and 11.
+**Risk:** HIGH — could break tunnel on network change.
+
+---
+
+## B-5: Change WireGuard default MTU from 1420 to 1280
+
+**Current:** SDK defaults to `MTU = 1420` in `writeWgConfig()`. Node Tester uses 1280.
+**Proposed:** Change default to 1280 (more compatible with restrictive networks and IPv6).
+**Why breaking:** Existing consumer apps may have tuned for 1420. Lower MTU means more packets for the same data (slight overhead). Some nodes may perform worse at 1280.
+**Risk:** LOW-MEDIUM — performance change, not a functional break.
+
+---
+
+## B-6: Implement `autoReconnect` as a real class
+
+**Current:** `autoReconnect()` exists as a simple polling function. README and GUIDE document a more sophisticated API with backoff, callbacks, and `.stop()`.
+**Proposed:** Rewrite as a proper class with the documented API.
+**Why breaking:** Existing callers of `autoReconnect()` get a different return shape. The polling interval, retry logic, and event emission may change behavior.
+**Risk:** MEDIUM — API shape change.
+
+---
+
+## B-7: Change `fullTunnel` default to `false` for V2Ray
+
+**Current:** `fullTunnel` defaults to `true` for all protocols. For V2Ray, this sets the system proxy.
+**Proposed:** V2Ray should default to `fullTunnel: false` (split tunnel — only proxied traffic through VPN). WireGuard stays `fullTunnel: true`.
+**Why breaking:** All existing V2Ray consumers would stop routing system traffic through VPN by default. Any app relying on the system proxy being auto-set would break.
+**Risk:** MEDIUM — behavior change for V2Ray consumers.
+
+---
+
+## How to Use This File
+
+When the user says **"do everything"** or **"fix everything"** — implement all suggestions EXCEPT items listed in this file. These items require the user to explicitly say "do B-1" or "implement B-3" etc.
+
+When the user says **"do everything including breaking"** — then implement these too, but confirm each one before proceeding.