nodmix 2026.5.25

package/docs/cli/policy.md

@@ -0,0 +1,418 @@
+---
+summary: "CLI reference for `nodmix policy` conformance checks"
+read_when:
+  - You want to check Nodmix settings against an authored policy.jsonc
+  - You want policy findings in doctor lint
+  - You need a policy attestation hash for audit evidence
+title: "Policy"
+---
+
+# `nodmix policy`
+
+`nodmix policy` is provided by the bundled Policy plugin. Policy is an
+enterprise conformance layer over existing Nodmix settings. It does not add a
+second configuration system. `policy.jsonc` defines authored requirements,
+Nodmix observes the active workspace as evidence, and policy health checks
+report drift through `doctor --lint`. The final conformance signal is a clean
+`doctor --lint` run; policy contributes findings to that shared lint surface
+instead of creating a separate health gate.
+
+Policy currently manages configured channels, MCP servers, model providers,
+network SSRF posture, and governed tool declarations. For example, IT or a
+workspace operator can record that Telegram is not an approved channel
+provider, restrict MCP servers and model refs to approved entries, require
+private-network fetch/browser access to remain disabled, require governed tools
+to carry risk and sensitivity metadata, then use `doctor --lint` as the shared
+conformance gate.
+
+Use policy when a workspace needs a durable statement such as "these channels
+must not be enabled" or "governed tools must declare approval metadata" and a
+repeatable way to prove that Nodmix still conforms to that statement. Use
+regular config and workspace docs alone when you only need local behavior and
+do not need policy findings or attestation output.
+
+## Quick start
+
+Enable the bundled Policy plugin before first use:
+
+```bash
+nodmix plugins enable policy
+```
+
+When policy is enabled, doctor can load policy health checks without activating
+arbitrary plugins. The plugin remains enabled if `policy.jsonc` is missing, so
+doctor can report the missing artifact.
+
+Policy is authored, not generated from the user's current settings. A minimal
+policy for channels, MCP servers, model providers, network posture, and tool
+metadata looks like this:
+
+```jsonc
+{
+  "channels": {
+    "denyRules": [
+      {
+        "id": "no-telegram",
+        "when": { "provider": "telegram" },
+        "reason": "Telegram is not approved for this workspace.",
+      },
+    ],
+  },
+  "mcp": {
+    "servers": {
+      "allow": ["docs"],
+      "deny": ["untrusted"],
+    },
+  },
+  "models": {
+    "providers": {
+      "allow": ["openai", "anthropic"],
+      "deny": ["openrouter"],
+    },
+  },
+  "network": {
+    "privateNetwork": {
+      "allow": false,
+    },
+  },
+  "tools": {
+    "requireMetadata": ["risk", "sensitivity", "owner"],
+  },
+}
+```
+
+The rules are the authority. A category block is only a namespace; checks run
+when a concrete rule is present. Nodmix reads current `channels.*` settings
+`mcp.servers.*`, `models.providers.*`, selected agent model refs, network SSRF
+settings, and `TOOLS.md` declarations as evidence, then reports observed state
+that does not conform.
+
+Run policy-only checks during authoring:
+
+```bash
+nodmix policy check
+nodmix policy check --json
+nodmix policy check --severity-min error
+```
+
+`policy check` runs only the policy check set and emits evidence, findings, and
+attestation hashes. The same findings also appear in `nodmix doctor --lint`
+when the Policy plugin is enabled.
+
+Example clean JSON output includes stable hashes that can be recorded by an
+operator or supervisor:
+
+```json
+{
+  "ok": true,
+  "attestation": {
+    "policy": {
+      "path": "policy.jsonc",
+      "hash": "sha256:..."
+    },
+    "workspace": {
+      "scope": "policy",
+      "hash": "sha256:..."
+    },
+    "findingsHash": "sha256:...",
+    "attestationHash": "sha256:..."
+  },
+  "checksRun": 5,
+  "checksSkipped": 0,
+  "findings": []
+}
+```
+
+## Configure policy
+
+Policy config lives under `plugins.entries.policy.config`.
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "policy": {
+        "enabled": true,
+        "config": {
+          "enabled": true,
+          "path": "policy.jsonc",
+          "workspaceRepairs": false,
+          "expectedHash": "sha256:...",
+          "expectedAttestationHash": "sha256:...",
+        },
+      },
+    },
+  },
+}
+```
+
+| Setting                   | Purpose                                                         |
+| ------------------------- | --------------------------------------------------------------- |
+| `enabled`                 | Enable policy checks even before `policy.jsonc` exists.         |
+| `workspaceRepairs`        | Allow `doctor --fix` to edit policy-managed workspace settings. |
+| `expectedHash`            | Optional hash-lock for the approved policy artifact.            |
+| `expectedAttestationHash` | Optional hash-lock for the last accepted clean policy check.    |
+| `path`                    | Workspace-relative location of the policy artifact.             |
+
+Set `plugins.entries.policy.config.enabled` to `false` to disable policy checks
+for a workspace while leaving the plugin installed.
+
+Tool metadata requirements are authored in `policy.jsonc` with
+`tools.requireMetadata`, for example `["risk", "sensitivity", "owner"]`.
+
+## Accept policy state
+
+Example JSON output:
+
+```json
+{
+  "ok": true,
+  "attestation": {
+    "checkedAt": "2026-05-10T20:00:00.000Z",
+    "policy": {
+      "path": "policy.jsonc",
+      "hash": "sha256:..."
+    },
+    "workspace": {
+      "scope": "policy",
+      "hash": "sha256:..."
+    },
+    "findingsHash": "sha256:...",
+    "attestationHash": "sha256:..."
+  },
+  "evidence": {
+    "channels": [
+      {
+        "id": "telegram",
+        "provider": "telegram",
+        "source": "oc://nodmix.config/channels/telegram",
+        "enabled": false
+      }
+    ],
+    "mcpServers": [
+      {
+        "id": "docs",
+        "transport": "stdio",
+        "source": "oc://nodmix.config/mcp/servers/docs",
+        "command": "npx"
+      }
+    ],
+    "modelProviders": [
+      {
+        "id": "openai",
+        "source": "oc://nodmix.config/models/providers/openai"
+      }
+    ],
+    "modelRefs": [
+      {
+        "ref": "openai/gpt-5.5",
+        "provider": "openai",
+        "model": "gpt-5.5",
+        "source": "oc://nodmix.config/agents/defaults/model"
+      }
+    ],
+    "network": [
+      {
+        "id": "browser-private-network",
+        "source": "oc://nodmix.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",
+        "value": false
+      }
+    ],
+    "tools": [
+      {
+        "id": "deploy",
+        "source": "oc://TOOLS.md/tools/deploy",
+        "line": 12,
+        "risk": "critical",
+        "sensitivity": "restricted",
+        "capabilities": ["IRREVERSIBLE_EXTERNAL"]
+      }
+    ]
+  },
+  "checksRun": 15,
+  "checksSkipped": 0,
+  "findings": []
+}
+```
+
+The policy hash identifies the authored rule artifact. The evidence block
+records the observed Nodmix state used by the policy checks. The
+`workspace.hash` value identifies that evidence payload for the checked scope.
+The findings hash identifies the exact finding set returned by the check.
+`checkedAt` records when the evaluation ran. The attestation hash identifies
+the stable claim: policy hash, evidence hash, findings hash, and whether the
+result was clean. It intentionally does not include `checkedAt`, so the same
+policy state produces the same attestation across repeated checks. Together,
+these form the audit tuple for this policy check.
+
+If a later gateway or supervisor uses policy to block, approve, or annotate a
+runtime action, it should record the attestation hash from the last clean policy
+check. `checkedAt` stays in JSON output for audit logs, but is not part of the
+stable attestation hash.
+
+Use this lifecycle when accepting policy state:
+
+1. Author or review `policy.jsonc`.
+2. Run `nodmix policy check --json`.
+3. If the result is clean, record `attestation.policy.hash` as `expectedHash`.
+4. Record `attestation.attestationHash` as `expectedAttestationHash`.
+5. Re-run `nodmix doctor --lint` in CI or release gates.
+
+If policy rules change intentionally, update both accepted hashes from a clean
+check. If workspace settings change intentionally but policy stays the same,
+only `expectedAttestationHash` usually changes.
+
+`nodmix policy watch` runs the same check repeatedly and reports when the
+current evidence no longer matches `expectedAttestationHash`:
+
+```bash
+nodmix policy watch --json
+```
+
+Use `--once` in CI or scripts that only need one drift evaluation. Without
+`--once`, the command polls every two seconds by default; use `--interval-ms` to
+choose a different interval.
+
+## Findings
+
+Policy currently verifies:
+
+| Check id                                 | Finding                                                               |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| `policy/policy-jsonc-missing`            | Policy is enabled but `policy.jsonc` is missing.                      |
+| `policy/policy-jsonc-invalid`            | Policy cannot be parsed or contains malformed rule entries.           |
+| `policy/policy-hash-mismatch`            | Policy does not match configured `expectedHash`.                      |
+| `policy/attestation-hash-mismatch`       | Current policy evidence no longer matches the accepted attestation.   |
+| `policy/channels-denied-provider`        | An enabled channel matches a channel deny rule.                       |
+| `policy/mcp-denied-server`               | A configured MCP server is denied by policy.                          |
+| `policy/mcp-unapproved-server`           | A configured MCP server is outside the allowlist.                     |
+| `policy/models-denied-provider`          | A configured model provider or model ref uses a denied provider.      |
+| `policy/models-unapproved-provider`      | A configured model provider or model ref is outside the allowlist.    |
+| `policy/network-private-access-enabled`  | A private-network SSRF escape hatch is enabled when policy denies it. |
+| `policy/tools-missing-risk-level`        | A governed tool declaration is missing risk metadata.                 |
+| `policy/tools-unknown-risk-level`        | A governed tool declaration uses an unknown risk value.               |
+| `policy/tools-missing-sensitivity-token` | A governed tool declaration is missing sensitivity metadata.          |
+| `policy/tools-missing-owner`             | A governed tool declaration is missing owner metadata.                |
+| `policy/tools-unknown-sensitivity-token` | A governed tool declaration uses an unknown sensitivity value.        |
+
+Policy findings can include both `target` and `requirement`. `target` is the
+observed workspace thing that does not conform. `requirement` is the authored
+policy rule that made it a finding. Both values are addresses today, usually
+`oc://` paths, but the field names describe their policy role rather than the
+address format.
+
+Example JSON finding:
+
+```json
+{
+  "checkId": "policy/channels-denied-provider",
+  "severity": "error",
+  "message": "Channel 'telegram' uses denied provider 'telegram'.",
+  "source": "policy",
+  "path": "nodmix config",
+  "ocPath": "oc://nodmix.config/channels/telegram",
+  "target": "oc://nodmix.config/channels/telegram",
+  "requirement": "oc://policy.jsonc/channels/denyRules/#0",
+  "fixHint": "Telegram is not approved for this workspace."
+}
+```
+
+Example tool finding:
+
+```json
+{
+  "checkId": "policy/tools-missing-risk-level",
+  "severity": "error",
+  "message": "TOOLS.md tool 'deploy' has no explicit risk classification.",
+  "source": "policy",
+  "path": "TOOLS.md",
+  "line": 12,
+  "ocPath": "oc://TOOLS.md/tools/deploy",
+  "target": "oc://TOOLS.md/tools/deploy",
+  "requirement": "oc://policy.jsonc/tools/requireMetadata"
+}
+```
+
+Example MCP finding:
+
+```json
+{
+  "checkId": "policy/mcp-unapproved-server",
+  "severity": "error",
+  "message": "MCP server 'remote' is not in the policy allowlist.",
+  "source": "policy",
+  "path": "nodmix config",
+  "ocPath": "oc://nodmix.config/mcp/servers/remote",
+  "target": "oc://nodmix.config/mcp/servers/remote",
+  "requirement": "oc://policy.jsonc/mcp/servers/allow"
+}
+```
+
+Example model-provider finding:
+
+```json
+{
+  "checkId": "policy/models-unapproved-provider",
+  "severity": "error",
+  "message": "Model ref 'anthropic/claude-sonnet-4.7' uses unapproved provider 'anthropic'.",
+  "source": "policy",
+  "path": "nodmix config",
+  "ocPath": "oc://nodmix.config/agents/defaults/model/fallbacks/#0",
+  "target": "oc://nodmix.config/agents/defaults/model/fallbacks/#0",
+  "requirement": "oc://policy.jsonc/models/providers/allow"
+}
+```
+
+Example network finding:
+
+```json
+{
+  "checkId": "policy/network-private-access-enabled",
+  "severity": "error",
+  "message": "Network setting 'browser-private-network' allows private-network access.",
+  "source": "policy",
+  "path": "nodmix config",
+  "ocPath": "oc://nodmix.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",
+  "target": "oc://nodmix.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",
+  "requirement": "oc://policy.jsonc/network/privateNetwork/allow"
+}
+```
+
+## Repair
+
+`doctor --lint` and `policy check` are read-only.
+
+`doctor --fix` only edits policy-managed workspace settings when
+`workspaceRepairs` is explicitly enabled. Without that opt-in, policy checks
+report what they would repair and leave settings unchanged.
+
+In this version, repair can disable channels that are enabled in Nodmix config
+but denied by `channels.denyRules`. Enable `workspaceRepairs` only after the
+policy file has been reviewed, because a valid deny rule can turn off a
+configured channel:
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "policy": {
+        "config": {
+          "workspaceRepairs": true,
+        },
+      },
+    },
+  },
+}
+```
+
+## Exit codes
+
+| Command        | `0`                                       | `1`                                              | `2`                          |
+| -------------- | ----------------------------------------- | ------------------------------------------------ | ---------------------------- |
+| `policy check` | No findings at the threshold.             | One or more findings met the threshold.          | Argument or runtime failure. |
+| `policy watch` | No findings and accepted hash is current. | Findings exist or accepted attestation is stale. | Argument or runtime failure. |
+
+## Related
+
+- [Doctor lint mode](/cli/doctor#lint-mode)
+- [Path CLI](/cli/path)

package/docs/cli/proxy.md

@@ -0,0 +1,89 @@
+---
+summary: "CLI reference for `nodmix proxy`, including operator-managed proxy validation and the local debug proxy capture inspector"
+read_when:
+  - You need to validate operator-managed proxy routing before deployment
+  - You need to capture Nodmix transport traffic locally for debugging
+  - You want to inspect debug proxy sessions, blobs, or built-in query presets
+title: "Proxy"
+---
+
+# `nodmix proxy`
+
+Validate operator-managed proxy routing, or run the local explicit debug proxy
+and inspect captured traffic.
+
+Use `validate` to preflight an operator-managed forward proxy before enabling
+Nodmix proxy routing. The other commands are debugging tools for
+transport-level investigation: they can start a local proxy, run a child command
+with capture enabled, list capture sessions, query common traffic patterns, read
+captured blobs, and purge local capture data.
+
+## Commands
+
+```bash
+nodmix proxy start [--host <host>] [--port <port>]
+nodmix proxy run [--host <host>] [--port <port>] -- <cmd...>
+nodmix proxy validate [--json] [--proxy-url <url>] [--proxy-ca-file <path>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
+nodmix proxy coverage
+nodmix proxy sessions [--limit <count>]
+nodmix proxy query --preset <name> [--session <id>]
+nodmix proxy blob --id <blobId>
+nodmix proxy purge
+```
+
+## Validate
+
+`nodmix proxy validate` checks the effective operator-managed proxy URL from
+`--proxy-url`, config, or `NODMIX_PROXY_URL`. Managed proxy URLs can use
+`http://` for a plain forward-proxy listener or `https://` when Nodmix must
+open TLS to the proxy endpoint before sending proxy requests. It reports a
+config problem when no proxy is enabled and configured; use `--proxy-url` for a
+one-off preflight before changing config. Add `--proxy-ca-file` to trust a
+private CA for the TLS connection to an HTTPS proxy endpoint. By default it
+verifies that a public destination succeeds through the proxy and that the proxy
+cannot reach a temporary loopback canary. Custom denied destinations are
+fail-closed: HTTP responses and ambiguous transport failures both fail unless
+you can verify a deployment-specific denial signal separately. Add
+`--apns-reachable` to also open an APNs HTTP/2 CONNECT tunnel through the proxy
+and confirm sandbox APNs responds; the probe uses an intentionally invalid
+provider token, so an APNs `403 InvalidProviderToken` response is a successful
+reachability signal.
+
+Options:
+
+- `--json`: print machine-readable JSON.
+- `--proxy-url <url>`: validate this `http://` or `https://` proxy URL instead of config or env.
+- `--proxy-ca-file <path>`: trust this PEM CA file for TLS verification of an HTTPS proxy endpoint.
+- `--allowed-url <url>`: add a destination expected to succeed through the proxy. Repeat to check multiple destinations.
+- `--denied-url <url>`: add a destination expected to be blocked by the proxy. Repeat to check multiple destinations.
+- `--apns-reachable`: also verify sandbox APNs HTTP/2 is reachable through the proxy.
+- `--apns-authority <url>`: APNs authority to probe with `--apns-reachable` (`https://api.sandbox.push.apple.com` by default; production is `https://api.push.apple.com`).
+- `--timeout-ms <ms>`: per-request timeout in milliseconds.
+
+See [Network Proxy](/security/network-proxy) for deployment guidance and denial
+semantics.
+
+## Query presets
+
+`nodmix proxy query --preset <name>` accepts:
+
+- `double-sends`
+- `retry-storms`
+- `cache-busting`
+- `ws-duplicate-frames`
+- `missing-ack`
+- `error-bursts`
+
+## Notes
+
+- `start` defaults to `127.0.0.1` unless `--host` is set.
+- `run` starts a local debug proxy and then runs the command after `--`.
+- The debug proxy's direct upstream forwarding opens upstream sockets for diagnostics. When Nodmix managed proxy mode is active, direct forwarding for proxy requests and CONNECT tunnels is disabled by default; set `NODMIX_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` only for approved local diagnostics.
+- `validate` exits with code 1 when proxy config or destination checks fail.
+- Captures are local debugging data; use `nodmix proxy purge` when finished.
+
+## Related
+
+- [CLI reference](/cli)
+- [Network Proxy](/security/network-proxy)
+- [Trusted proxy auth](/gateway/trusted-proxy-auth)

package/docs/cli/qr.md

@@ -0,0 +1,56 @@
+---
+summary: "CLI reference for `nodmix qr` (generate mobile pairing QR + setup code)"
+read_when:
+  - You want to pair a mobile node app with a gateway quickly
+  - You need setup-code output for remote/manual sharing
+title: "QR"
+---
+
+# `nodmix qr`
+
+Generate a mobile pairing QR and setup code from your current Gateway configuration.
+
+## Usage
+
+```bash
+nodmix qr
+nodmix qr --setup-code-only
+nodmix qr --json
+nodmix qr --remote
+nodmix qr --url wss://gateway.example/ws
+```
+
+## Options
+
+- `--remote`: prefer `gateway.remote.url`; if it is unset, `gateway.tailscale.mode=serve|funnel` can still provide the remote public URL
+- `--url <url>`: override gateway URL used in payload
+- `--public-url <url>`: override public URL used in payload
+- `--token <token>`: override which gateway token the bootstrap flow authenticates against
+- `--password <password>`: override which gateway password the bootstrap flow authenticates against
+- `--setup-code-only`: print only setup code
+- `--no-ascii`: skip ASCII QR rendering
+- `--json`: emit JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`)
+
+## Notes
+
+- `--token` and `--password` are mutually exclusive.
+- The setup code itself now carries an opaque short-lived `bootstrapToken`, not the shared gateway token/password.
+- Built-in setup-code bootstrap returns a primary `node` token with `scopes: []` plus a bounded `operator` handoff token for trusted mobile onboarding.
+- The handed-off operator token is limited to `operator.approvals`, `operator.read`, and `operator.write`; `operator.admin`, `operator.pairing`, and `operator.talk.secrets` require a separate approved operator pairing or token flow.
+- Mobile pairing fails closed for Tailscale/public `ws://` gateway URLs. Private LAN addresses and `.local` Bonjour hosts remain supported over `ws://`, but Tailscale/public mobile routes should use Tailscale Serve/Funnel or a `wss://` gateway URL.
+- With `--remote`, Nodmix requires either `gateway.remote.url` or
+  `gateway.tailscale.mode=serve|funnel`.
+- With `--remote`, if effectively active remote credentials are configured as SecretRefs and you do not pass `--token` or `--password`, the command resolves them from the active gateway snapshot. If gateway is unavailable, the command fails fast.
+- Without `--remote`, local gateway auth SecretRefs are resolved when no CLI auth override is passed:
+  - `gateway.auth.token` resolves when token auth can win (explicit `gateway.auth.mode="token"` or inferred mode where no password source wins).
+  - `gateway.auth.password` resolves when password auth can win (explicit `gateway.auth.mode="password"` or inferred mode with no winning token from auth/env).
+- If both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs) and `gateway.auth.mode` is unset, setup-code resolution fails until mode is set explicitly.
+- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
+- After scanning, approve device pairing with:
+  - `nodmix devices list`
+  - `nodmix devices approve <requestId>`
+
+## Related
+
+- [CLI reference](/cli)
+- [Pairing](/cli/pairing)

package/docs/cli/reset.md

@@ -0,0 +1,39 @@
+---
+summary: "CLI reference for `nodmix reset` (reset local state/config)"
+read_when:
+  - You want to wipe local state while keeping the CLI installed
+  - You want a dry-run of what would be removed
+title: "Reset"
+---
+
+# `nodmix reset`
+
+Reset local config/state (keeps the CLI installed).
+
+Options:
+
+- `--scope <scope>`: `config`, `config+creds+sessions`, or `full`
+- `--yes`: skip confirmation prompts
+- `--non-interactive`: disable prompts; requires `--scope` and `--yes`
+- `--dry-run`: print actions without removing files
+
+Examples:
+
+```bash
+nodmix backup create
+nodmix reset
+nodmix reset --dry-run
+nodmix reset --scope config --yes --non-interactive
+nodmix reset --scope config+creds+sessions --yes --non-interactive
+nodmix reset --scope full --yes --non-interactive
+```
+
+Notes:
+
+- Run `nodmix backup create` first if you want a restorable snapshot before removing local state.
+- If you omit `--scope`, `nodmix reset` uses an interactive prompt to choose what to remove.
+- `--non-interactive` is only valid when both `--scope` and `--yes` are set.
+
+## Related
+
+- [CLI reference](/cli)