nodmix 2026.5.25

package/docs/security/formal-verification.md

@@ -0,0 +1,170 @@
+---
+summary: Machine-checked security models for Nodmix's highest-risk paths.
+title: Formal verification (security models)
+read_when:
+  - Reviewing formal security model guarantees or limits
+  - Reproducing or updating TLA+/TLC security model checks
+permalink: /security/formal-verification/
+---
+
+This page tracks Nodmix's **formal security models** (TLA+/TLC today; more as needed).
+
+> Note: some older links may refer to the previous project name.
+
+**Goal (north star):** provide a machine-checked argument that Nodmix enforces its
+intended security policy (authorization, session isolation, tool gating, and
+misconfiguration safety), under explicit assumptions.
+
+**What this is (today):** an executable, attacker-driven **security regression suite**:
+
+- Each claim has a runnable model-check over a finite state space.
+- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class.
+
+**What this is not (yet):** a proof that "Nodmix is secure in all respects" or that the full TypeScript implementation is correct.
+
+## Where the models live
+
+Models are maintained in a separate repo: [vignesh07/nodmix-formal-models](https://github.com/vignesh07/nodmix-formal-models).
+
+## Important caveats
+
+- These are **models**, not the full TypeScript implementation. Drift between model and code is possible.
+- Results are bounded by the state space explored by TLC; "green" does not imply security beyond the modeled assumptions and bounds.
+- Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs).
+
+## Reproducing results
+
+Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer:
+
+- CI-run models with public artifacts (counterexample traces, run logs)
+- a hosted "run this model" workflow for small, bounded checks
+
+Getting started:
+
+```bash
+git clone https://github.com/vignesh07/nodmix-formal-models
+cd nodmix-formal-models
+
+# Java 11+ required (TLC runs on the JVM).
+# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
+
+make <target>
+```
+
+### Gateway exposure and open gateway misconfiguration
+
+**Claim:** binding beyond loopback without auth can make remote compromise possible / increases exposure; token/password blocks unauth attackers (per the model assumptions).
+
+- Green runs:
+  - `make gateway-exposure-v2`
+  - `make gateway-exposure-v2-protected`
+- Red (expected):
+  - `make gateway-exposure-v2-negative`
+
+See also: `docs/gateway-exposure-matrix.md` in the models repo.
+
+### Node exec pipeline (highest-risk capability)
+
+**Claim:** `exec host=node` requires (a) node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay (in the model).
+
+- Green runs:
+  - `make nodes-pipeline`
+  - `make approvals-token`
+- Red (expected):
+  - `make nodes-pipeline-negative`
+  - `make approvals-token-negative`
+
+### Pairing store (DM gating)
+
+**Claim:** pairing requests respect TTL and pending-request caps.
+
+- Green runs:
+  - `make pairing`
+  - `make pairing-cap`
+- Red (expected):
+  - `make pairing-negative`
+  - `make pairing-cap-negative`
+
+### Ingress gating (mentions + control-command bypass)
+
+**Claim:** in group contexts requiring mention, an unauthorized "control command" cannot bypass mention gating.
+
+- Green:
+  - `make ingress-gating`
+- Red (expected):
+  - `make ingress-gating-negative`
+
+### Routing/session-key isolation
+
+**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked/configured.
+
+- Green:
+  - `make routing-isolation`
+- Red (expected):
+  - `make routing-isolation-negative`
+
+## v1++: additional bounded models (concurrency, retries, trace correctness)
+
+These are follow-on models that tighten fidelity around real-world failure modes (non-atomic updates, retries, and message fan-out).
+
+### Pairing store concurrency / idempotency
+
+**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., "check-then-write" must be atomic / locked; refresh shouldn't create duplicates).
+
+What it means:
+
+- Under concurrent requests, you can't exceed `MaxPending` for a channel.
+- Repeated requests/refreshes for the same `(channel, sender)` should not create duplicate live pending rows.
+
+- Green runs:
+  - `make pairing-race` (atomic/locked cap check)
+  - `make pairing-idempotency`
+  - `make pairing-refresh`
+  - `make pairing-refresh-race`
+- Red (expected):
+  - `make pairing-race-negative` (non-atomic begin/commit cap race)
+  - `make pairing-idempotency-negative`
+  - `make pairing-refresh-negative`
+  - `make pairing-refresh-race-negative`
+
+### Ingress trace correlation / idempotency
+
+**Claim:** ingestion should preserve trace correlation across fan-out and be idempotent under provider retries.
+
+What it means:
+
+- When one external event becomes multiple internal messages, every part keeps the same trace/event identity.
+- Retries do not result in double-processing.
+- If provider event IDs are missing, dedupe falls back to a safe key (e.g., trace ID) to avoid dropping distinct events.
+
+- Green:
+  - `make ingress-trace`
+  - `make ingress-trace2`
+  - `make ingress-idempotency`
+  - `make ingress-dedupe-fallback`
+- Red (expected):
+  - `make ingress-trace-negative`
+  - `make ingress-trace2-negative`
+  - `make ingress-idempotency-negative`
+  - `make ingress-dedupe-fallback-negative`
+
+### Routing dmScope precedence + identityLinks
+
+**Claim:** routing must keep DM sessions isolated by default, and only collapse sessions when explicitly configured (channel precedence + identity links).
+
+What it means:
+
+- Channel-specific dmScope overrides must win over global defaults.
+- identityLinks should collapse only within explicit linked groups, not across unrelated peers.
+
+- Green:
+  - `make routing-precedence`
+  - `make routing-identitylinks`
+- Red (expected):
+  - `make routing-precedence-negative`
+  - `make routing-identitylinks-negative`
+
+## Related
+
+- [Threat model](/security/THREAT-MODEL-ATLAS)
+- [Contributing to the threat model](/security/CONTRIBUTING-THREAT-MODEL)

package/docs/security/incident-response.md

@@ -0,0 +1,59 @@
+---
+summary: "How Nodmix triages, responds to, and follows up on security incidents"
+title: "Incident response"
+read_when:
+  - Responding to a security report or suspected security incident
+  - Preparing a coordinated disclosure or patched security release
+  - Reviewing post-incident follow-up expectations
+---
+
+## 1. Detection and triage
+
+We monitor security signals from:
+
+- GitHub Security Advisories (GHSA) and private vulnerability reports.
+- Public GitHub issues/discussions when reports are not sensitive.
+- Automated signals (for example Dependabot, CodeQL, npm advisories, and secret scanning).
+
+Initial triage:
+
+1. Confirm affected component, version, and trust boundary impact.
+2. Classify as security issue vs hardening/no-action using the repository `SECURITY.md` scope and out-of-scope rules.
+3. An incident owner responds accordingly.
+
+## 2. Assessment
+
+Severity guide:
+
+- **Critical:** Package/release/repository compromise, active exploitation, or unauthenticated trust-boundary bypass with high-impact control or data exposure.
+- **High:** Verified trust-boundary bypass requiring limited preconditions (for example authenticated but unauthorized high-impact action), or exposure of Nodmix-owned sensitive credentials.
+- **Medium:** Significant security weakness with practical impact but constrained exploitability or substantial prerequisites.
+- **Low:** Defense-in-depth findings, narrowly scoped denial-of-service, or hardening/parity gaps without a demonstrated trust-boundary bypass.
+
+## 3. Response
+
+1. Acknowledge receipt to the reporter (private when sensitive).
+2. Reproduce on supported releases and latest `main`, then implement and validate a patch with regression coverage.
+3. For critical/high incidents, prepare patched release(s) as fast as practical.
+4. For medium/low incidents, patch in normal release flow and document mitigation guidance.
+
+## 4. Communication
+
+We communicate through:
+
+- GitHub Security Advisories in the affected repository.
+- Release notes/changelog entries for fixed versions.
+- Direct reporter follow-up on status and resolution.
+
+Disclosure policy:
+
+- Critical/high incidents should receive coordinated disclosure, with CVE issuance when appropriate.
+- Low-risk hardening findings may be documented in release notes or advisories without CVE, depending on impact and user exposure.
+
+## 5. Recovery and follow-up
+
+After shipping the fix:
+
+1. Verify remediations in CI and release artifacts.
+2. Run a short post-incident review (timeline, root cause, detection gap, prevention plan).
+3. Add follow-up hardening/tests/docs tasks and track them to completion.

package/docs/security/network-proxy.md

@@ -0,0 +1,268 @@
+---
+summary: "How to route Nodmix runtime HTTP and WebSocket traffic through an operator-managed filtering proxy"
+title: "Network proxy"
+read_when:
+  - You want defense-in-depth against SSRF and DNS rebinding attacks
+  - Configuring an external forward proxy for Nodmix runtime traffic
+---
+
+Nodmix can route runtime HTTP and WebSocket traffic through an operator-managed forward proxy. This is optional defense in depth for deployments that want central egress control, stronger SSRF protection, and better network auditability.
+
+Nodmix does not ship, download, start, configure, or certify a proxy. You run the proxy technology that fits your environment, and Nodmix routes normal process-local HTTP and WebSocket clients through it.
+
+## Why use a proxy
+
+A proxy gives operators one network control point for outbound HTTP and WebSocket traffic. That can be useful even outside SSRF hardening:
+
+- Central policy: maintain one egress policy instead of relying on every application HTTP call site to get network rules right.
+- Connect-time checks: evaluate the destination after DNS resolution and immediately before the proxy opens the upstream connection.
+- DNS rebinding defense: reduce the gap between an application-level DNS check and the actual outbound connection.
+- Broader JavaScript coverage: route ordinary `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch, and similar clients through the same path.
+- Auditability: log allowed and denied destinations at the egress boundary.
+- Operational control: enforce destination rules, network segmentation, rate limits, or outbound allowlists without rebuilding Nodmix.
+
+Proxy routing is a process-level guardrail for normal HTTP and WebSocket egress. It gives operators a fail-closed path for routing supported JavaScript HTTP clients through their own filtering proxy, but it is not an OS-level network sandbox and does not make Nodmix certify the proxy's destination policy.
+
+## How Nodmix routes traffic
+
+When `proxy.enabled=true` and a proxy URL is configured, protected runtime processes such as `nodmix gateway run`, `nodmix node run`, and `nodmix agent --local` route normal HTTP and WebSocket egress through the configured proxy:
+
+```text
+Nodmix process
+  fetch                  -> operator-managed filtering proxy -> public internet
+  node:http and https    -> operator-managed filtering proxy -> public internet
+  WebSocket clients      -> operator-managed filtering proxy -> public internet
+```
+
+The public contract is the routing behavior, not the internal Node hooks used to implement it. Nodmix Gateway control-plane WebSocket clients use a narrow direct path for local loopback Gateway RPC traffic when the Gateway URL uses `localhost` or a literal loopback IP such as `127.0.0.1` or `[::1]`. That control-plane path must be able to reach loopback Gateways even when the operator proxy blocks loopback destinations. Normal runtime HTTP and WebSocket requests still use the configured proxy.
+
+Internally, Nodmix installs Proxyline as the process-level routing runtime for this feature. Proxyline covers `fetch`, undici-backed clients, Node core `node:http` / `node:https` callers, common WebSocket clients, and helper-created CONNECT tunnels. Managed proxy mode replaces caller-provided Node HTTP agents so explicit agents do not accidentally bypass the operator proxy.
+
+Some plugins own custom transports that need explicit proxy wiring even when process-level routing exists. For example, Telegram's Bot API transport uses its own HTTP/1 undici dispatcher and therefore honors process proxy env plus the managed `NODMIX_PROXY_URL` fallback in that owner-specific transport path.
+
+The proxy URL itself can use either `http://` or `https://`. These schemes describe the connection from Nodmix to the proxy endpoint:
+
+- `http://proxy.example:3128`: Nodmix opens a plain TCP connection to the forward proxy and sends HTTP proxy requests, including `CONNECT` for HTTPS destinations.
+- `https://proxy.example:8443`: Nodmix opens TLS to the proxy endpoint, verifies the proxy certificate, and then sends HTTP proxy requests inside that TLS session.
+
+Destination HTTPS is separate from proxy endpoint TLS. For an HTTPS destination, Nodmix still asks the proxy for an HTTP `CONNECT` tunnel and then starts destination TLS through that tunnel.
+
+While the proxy is active, Nodmix clears `no_proxy` and `NO_PROXY`. Those bypass lists are destination-based, so leaving `localhost` or `127.0.0.1` there would let high-risk SSRF targets skip the filtering proxy.
+
+On shutdown, Nodmix restores the previous proxy environment and resets cached process routing state.
+
+## Related proxy terms
+
+- `proxy.enabled` / `proxy.proxyUrl`: outbound forward-proxy routing for Nodmix runtime egress. This page documents that feature.
+- `gateway.auth.mode: "trusted-proxy"`: inbound identity-aware reverse-proxy authentication for Gateway access. See [Trusted proxy auth](/gateway/trusted-proxy-auth).
+- `nodmix proxy`: local debug proxy and capture inspector for development and support. See [nodmix proxy](/cli/proxy).
+- `tools.web.fetch.useTrustedEnvProxy`: opt-in for `web_fetch` to let an operator-controlled HTTP(S) env proxy resolve DNS while keeping default strict DNS pinning and hostname policy. See [Web fetch](/tools/web-fetch#trusted-env-proxy).
+- Channel or provider-specific proxy settings: owner-specific overrides for a particular transport. Prefer the managed network proxy when the goal is central egress control across the runtime.
+
+## Configuration
+
+```yaml
+proxy:
+  enabled: true
+  proxyUrl: http://127.0.0.1:3128
+```
+
+For an HTTPS proxy endpoint with a private proxy CA:
+
+```yaml
+proxy:
+  enabled: true
+  proxyUrl: https://proxy.corp.example:8443
+  tls:
+    caFile: /etc/nodmix/proxy-ca.pem
+```
+
+You can also provide the URL through the environment, while keeping `proxy.enabled=true` in config:
+
+```bash
+NODMIX_PROXY_URL=http://127.0.0.1:3128 nodmix gateway run
+```
+
+`proxy.proxyUrl` takes precedence over `NODMIX_PROXY_URL`.
+
+### Gateway Loopback Mode
+
+Local Gateway control-plane clients usually connect to a loopback WebSocket such as `ws://127.0.0.1:18789`. Use `proxy.loopbackMode` to choose how that traffic behaves while the managed proxy is active:
+
+```yaml
+proxy:
+  enabled: true
+  proxyUrl: http://127.0.0.1:3128
+  loopbackMode: gateway-only # gateway-only, proxy, or block
+```
+
+- `gateway-only` (default): Nodmix registers the Gateway loopback authority in Proxyline's managed bypass policy so local Gateway WebSocket traffic can connect directly. Custom loopback Gateway ports work because the active Gateway URL's host and port are registered.
+- `proxy`: Nodmix does not register a Gateway loopback bypass, so local Gateway traffic is sent through the managed proxy. If the proxy is remote, it must provide special routing for the Nodmix host's loopback service, such as mapping it to a proxy-reachable hostname, IP, or tunnel. Standard remote proxies resolve `127.0.0.1` and `localhost` from the proxy host, not from the Nodmix host.
+- `block`: Nodmix denies loopback Gateway control-plane connections before opening a socket.
+
+If `enabled=true` but no valid proxy URL is configured, protected commands fail startup instead of falling back to direct network access.
+
+For managed gateway services started with `nodmix gateway start`, prefer storing the URL in config:
+
+```bash
+nodmix config set proxy.enabled true
+nodmix config set proxy.proxyUrl http://127.0.0.1:3128
+nodmix gateway install --force
+nodmix gateway start
+```
+
+The environment fallback is best for foreground runs. If you use it with an installed service, put `NODMIX_PROXY_URL` in the service durable environment, such as `$NODMIX_STATE_DIR/.env` or `~/.nodmix/.env`, then reinstall the service so launchd, systemd, or Scheduled Tasks starts the gateway with that value.
+
+For `nodmix --container ...` commands, Nodmix forwards `NODMIX_PROXY_URL` into the container-targeted child CLI when it is set. The URL must be reachable from inside the container; `127.0.0.1` refers to the container itself, not the host. Nodmix rejects loopback proxy URLs for container-targeted commands unless you explicitly override that safety check.
+
+## Proxy Requirements
+
+The proxy policy is the security boundary. Nodmix cannot verify that the proxy blocks the right targets.
+
+Configure the proxy to:
+
+- Bind only to loopback or a private trusted interface.
+- Restrict access so only the Nodmix process, host, container, or service account can use it.
+- Resolve destinations itself and block destination IPs after DNS resolution.
+- Apply policy at connect time for both plain HTTP requests and HTTPS `CONNECT` tunnels.
+- Reject destination-based bypasses for loopback, private, link-local, metadata, multicast, reserved, or documentation ranges.
+- Avoid hostname allowlists unless you fully trust the DNS resolution path.
+- Log destination, decision, status, and reason without logging request bodies, authorization headers, cookies, or other secrets.
+- Keep proxy policy under version control and review changes like security-sensitive configuration.
+
+## Recommended blocked destinations
+
+Use this denylist as the starting point for any forward proxy, firewall, or egress policy.
+
+Nodmix application-level classifier logic lives in `src/infra/net/ssrf.ts` and `src/shared/net/ip.ts`. The relevant parity hooks are `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX`, and the embedded IPv4 sentinel handling for NAT64, 6to4, Teredo, ISATAP, and IPv4-mapped forms. Those files are useful references when maintaining an external proxy policy, but Nodmix does not automatically export or enforce those rules in your proxy.
+
+| Range or host                                                                        | Why to block                                         |
+| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| `127.0.0.0/8`, `localhost`, `localhost.localdomain`                                  | IPv4 loopback                                        |
+| `::1/128`                                                                            | IPv6 loopback                                        |
+| `0.0.0.0/8`, `::/128`                                                                | Unspecified and this-network addresses               |
+| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`                                      | RFC1918 private networks                             |
+| `169.254.0.0/16`, `fe80::/10`                                                        | Link-local addresses and common cloud metadata paths |
+| `169.254.169.254`, `metadata.google.internal`                                        | Cloud metadata services                              |
+| `100.64.0.0/10`                                                                      | Carrier-grade NAT shared address space               |
+| `198.18.0.0/15`, `2001:2::/48`                                                       | Benchmarking ranges                                  |
+| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-use and documentation ranges                 |
+| `224.0.0.0/4`, `ff00::/8`                                                            | Multicast                                            |
+| `240.0.0.0/4`                                                                        | Reserved IPv4                                        |
+| `fc00::/7`, `fec0::/10`                                                              | IPv6 local/private ranges                            |
+| `100::/64`, `2001:20::/28`                                                           | IPv6 discard and ORCHIDv2 ranges                     |
+| `64:ff9b::/96`, `64:ff9b:1::/48`                                                     | NAT64 prefixes with embedded IPv4                    |
+| `2002::/16`, `2001::/32`                                                             | 6to4 and Teredo with embedded IPv4                   |
+| `::/96`, `::ffff:0:0/96`                                                             | IPv4-compatible and IPv4-mapped IPv6                 |
+
+If your cloud provider or network platform documents additional metadata hosts or reserved ranges, add those too.
+
+## Validation
+
+Validate the proxy from the same host, container, or service account that runs Nodmix:
+
+```bash
+nodmix proxy validate --proxy-url http://127.0.0.1:3128
+```
+
+For an HTTPS proxy endpoint signed by a private CA:
+
+```bash
+nodmix proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/nodmix/proxy-ca.pem
+```
+
+By default, when no custom destinations are provided, the command checks that `https://example.com/` succeeds and starts a temporary loopback canary that the proxy must not reach. The default denied check passes when the proxy returns a non-2xx denial response or blocks the canary with a transport failure; it fails if a successful response reaches the canary. If no proxy is enabled and configured, validation reports a config problem; use `--proxy-url` for a one-off preflight before changing config. Use `--allowed-url` and `--denied-url` to test deployment-specific expectations. Add `--apns-reachable` to also verify direct APNs HTTP/2 delivery can open a CONNECT tunnel through the proxy and receive a sandbox APNs response; the probe uses an intentionally invalid provider token, so `403 InvalidProviderToken` is expected and counts as reachable. Custom denied destinations are fail-closed: any HTTP response means the destination was reachable through the proxy, and any transport error is reported as inconclusive because Nodmix cannot prove the proxy blocked a reachable origin. On validation failure, the command exits with code 1.
+
+Use `--json` for automation. The JSON output contains the overall result, the effective proxy config source, any config errors, and each destination check. Proxy URL credentials are redacted in text and JSON output:
+
+```json
+{
+  "ok": true,
+  "config": {
+    "enabled": true,
+    "proxyUrl": "http://127.0.0.1:3128/",
+    "source": "override",
+    "errors": []
+  },
+  "checks": [
+    {
+      "kind": "allowed",
+      "url": "https://example.com/",
+      "ok": true,
+      "status": 200
+    },
+    {
+      "kind": "apns",
+      "url": "https://api.sandbox.push.apple.com",
+      "ok": true,
+      "status": 403
+    }
+  ]
+}
+```
+
+You can also validate manually with `curl`:
+
+```bash
+curl -x http://127.0.0.1:3128 https://example.com/
+curl -x http://127.0.0.1:3128 http://127.0.0.1/
+curl -x http://127.0.0.1:3128 http://169.254.169.254/
+```
+
+The public request should succeed. The loopback and metadata requests should be blocked by the proxy. For `nodmix proxy validate`, the built-in loopback canary can distinguish a proxy denial from a reachable origin. Custom `--denied-url` checks do not have that canary, so treat both HTTP responses and ambiguous transport failures as validation failures unless your proxy exposes a deployment-specific denial signal you can verify separately.
+
+## Proxy CA trust
+
+Use managed `proxy.tls.caFile` when the proxy endpoint itself uses a certificate signed by a private CA:
+
+```yaml
+proxy:
+  enabled: true
+  proxyUrl: https://proxy.corp.example:8443
+  tls:
+    caFile: /etc/nodmix/proxy-ca.pem
+```
+
+That CA is used for TLS verification of the proxy endpoint. It is not a destination MITM trust setting, a client certificate, or a replacement for the proxy's destination policy.
+
+Use `NODE_EXTRA_CA_CERTS` only when the whole Node process must trust an additional CA from process startup, such as when an enterprise TLS inspection system re-signs destination certificates for every HTTPS client in the process. `NODE_EXTRA_CA_CERTS` is process-global and must be present before Node starts. Prefer `proxy.tls.caFile` for HTTPS proxy endpoint trust because it is scoped to managed proxy routing.
+
+Then enable Nodmix proxy routing:
+
+```bash
+nodmix config set proxy.enabled true
+nodmix config set proxy.proxyUrl https://proxy.corp.example:8443
+nodmix config set proxy.tls.caFile /etc/nodmix/proxy-ca.pem
+nodmix gateway run
+```
+
+or set:
+
+```yaml
+proxy:
+  enabled: true
+  proxyUrl: https://proxy.corp.example:8443
+  tls:
+    caFile: /etc/nodmix/proxy-ca.pem
+```
+
+## Limits
+
+- The proxy improves coverage for process-local JavaScript HTTP and WebSocket clients, but it is not an OS-level network sandbox.
+- Gateway loopback control-plane traffic defaults to direct local bypass through `proxy.loopbackMode: "gateway-only"`. Nodmix implements that bypass by registering the active Gateway loopback authority in Proxyline's managed bypass policy. Operators can set `proxy.loopbackMode: "proxy"` to send Gateway loopback traffic through the managed proxy, or `proxy.loopbackMode: "block"` to deny loopback Gateway connections. See [Gateway Loopback Mode](#gateway-loopback-mode) for the remote-proxy caveat.
+- Raw `net`, `tls`, and `http2` sockets, native addons, and non-Nodmix child processes may bypass Node-level proxy routing unless they inherit and respect proxy environment variables. Forked Nodmix child CLIs inherit the managed proxy URL and `proxy.loopbackMode` state.
+- IRC is a raw TCP/TLS channel outside operator-managed forward proxy routing. In deployments that require all egress through that forward proxy, set `channels.irc.enabled=false` unless direct IRC egress is explicitly approved.
+- The local debug proxy is diagnostic tooling and its direct upstream forwarding for proxy requests and CONNECT tunnels is disabled by default while managed proxy mode is active; enable direct forwarding only for approved local diagnostics.
+- User local WebUIs and local model servers should be allowlisted in the operator proxy policy when needed; Nodmix does not expose a general local-network bypass for them.
+- Gateway control-plane proxy bypass is intentionally limited to `localhost` and literal loopback IP URLs. Use `ws://127.0.0.1:18789`, `ws://[::1]:18789`, or `ws://localhost:18789` for local direct Gateway control-plane connections; other hostnames route like ordinary hostname-based traffic.
+- Nodmix does not inspect, test, or certify your proxy policy.
+- Treat proxy policy changes as security-sensitive operational changes.
+
+| Surface                                                      | Managed proxy status                                                                               |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `fetch`, `node:http`, `node:https`, common WebSocket clients | Routed through managed proxy hooks when configured.                                                |
+| APNs direct HTTP/2                                           | Routed through the APNs managed CONNECT helper.                                                    |
+| Gateway control-plane loopback                               | Direct only for the configured local loopback Gateway URL.                                         |
+| Debug proxy upstream forwarding                              | Disabled while managed proxy mode is active unless explicitly enabled for local diagnostics.       |
+| IRC                                                          | Raw TCP/TLS; not proxied by managed HTTP proxy mode. Disable unless direct IRC egress is approved. |
+| Other raw `net`, `tls`, or `http2` client calls              | Must be classified by the raw socket guard before landing.                                         |

package/docs/snippets/plugin-publish/minimal-openclaw.plugin.json

@@ -0,0 +1,12 @@
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "description": "Adds a custom tool to Nodmix",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}

package/docs/snippets/plugin-publish/minimal-package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@myorg/nodmix-my-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "nodmix": {
+    "extensions": ["./index.ts"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "nodmixVersion": "2026.3.24-beta.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
+  }
+}

package/docs/start/bootstrapping.md

@@ -0,0 +1,49 @@
+---
+summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
+read_when:
+  - Understanding what happens on the first agent run
+  - Explaining where bootstrapping files live
+  - Debugging onboarding identity setup
+title: "Agent bootstrapping"
+sidebarTitle: "Bootstrapping"
+---
+
+Bootstrapping is the **first-run** ritual that prepares an agent workspace and
+collects identity details. It happens after onboarding, when the agent starts
+for the first time.
+
+## What bootstrapping does
+
+On the first agent run, Nodmix bootstraps the workspace (default
+`~/.nodmix/workspace`):
+
+- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
+- Runs a short Q&A ritual (one question at a time).
+- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
+- Removes `BOOTSTRAP.md` when finished so it only runs once.
+
+For embedded/local model runs, Nodmix keeps `BOOTSTRAP.md` out of the
+privileged system context. On the primary interactive first run, it still passes
+the file contents in the user prompt so models that do not reliably call the
+`read` tool can complete the ritual. If the current run cannot safely access the
+workspace, the agent gets a limited bootstrap note instead of a generic greeting.
+
+## Skipping bootstrapping
+
+To skip this for a pre-seeded workspace, run `nodmix onboard --skip-bootstrap`.
+
+## Where it runs
+
+Bootstrapping always runs on the **gateway host**. If the macOS app connects to
+a remote Gateway, the workspace and bootstrapping files live on that remote
+machine.
+
+<Note>
+When the Gateway runs on another machine, edit workspace files on the gateway
+host (for example, `user@gateway-host:~/.nodmix/workspace`).
+</Note>
+
+## Related docs
+
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Workspace layout: [Agent workspace](/concepts/agent-workspace)

package/docs/start/docs-directory.md

@@ -0,0 +1,69 @@
+---
+summary: "Curated links to the most used Nodmix docs."
+read_when:
+  - You want quick access to key docs pages
+title: "Docs directory"
+---
+
+<Note>
+This page is a curated index. If you are new, start with [Getting Started](/start/getting-started).
+For a complete map of the docs, see [Docs hubs](/start/hubs).
+</Note>
+
+## Start here
+
+- [Docs hubs (all pages linked)](/start/hubs)
+- [Help](/help)
+- [Configuration](/gateway/configuration)
+- [Configuration examples](/gateway/configuration-examples)
+- [Slash commands](/tools/slash-commands)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Updating and rollback](/install/updating)
+- [Pairing (DM and nodes)](/channels/pairing)
+- [Nix mode](/install/nix)
+- [Nodmix assistant setup](/start/nodmix)
+- [Skills](/tools/skills)
+- [Skills config](/tools/skills-config)
+- [Workspace templates](/reference/templates/AGENTS)
+- [RPC adapters](/reference/rpc)
+- [Gateway runbook](/gateway)
+- [Nodes (iOS and Android)](/nodes)
+- [Web surfaces (Control UI)](/web)
+- [Discovery and transports](/gateway/discovery)
+- [Remote access](/gateway/remote)
+
+## Providers and UX
+
+- [WebChat](/web/webchat)
+- [Control UI (browser)](/web/control-ui)
+- [Telegram](/channels/telegram)
+- [Discord](/channels/discord)
+- [Mattermost](/channels/mattermost)
+- [QQ Bot](/channels/qqbot)
+- [iMessage](/channels/imessage)
+- [Groups](/channels/groups)
+- [WhatsApp group messages](/channels/group-messages)
+- [Media images](/nodes/images)
+- [Media audio](/nodes/audio)
+
+## Companion apps
+
+- [macOS app](/platforms/macos)
+- [iOS app](/platforms/ios)
+- [Android app](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux app](/platforms/linux)
+
+## Operations and safety
+
+- [Sessions](/concepts/session)
+- [Cron jobs](/automation/cron-jobs)
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Gmail hooks (Pub/Sub)](/automation/cron-jobs#gmail-pubsub-integration)
+- [Security](/gateway/security)
+- [Troubleshooting](/gateway/troubleshooting)
+
+## Related
+
+- [Getting started](/start/getting-started)
+- [Docs hubs](/start/hubs)