fengming 0.3.9 → 0.3.11

package/docs/gateway/bonjour.md

@@ -1,303 +0,0 @@
----
-summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
-read_when:
-  - Debugging Bonjour discovery issues on macOS/iOS
-  - Changing mDNS service types, TXT records, or discovery UX
-title: "Bonjour discovery"
----
-
-FengMing can use Bonjour (mDNS / DNS-SD) to discover an active Gateway (WebSocket endpoint).
-Multicast `local.` browsing is a **LAN-only convenience**. The bundled `bonjour`
-plugin owns LAN advertising. It auto-starts on macOS hosts and is opt-in on
-Linux, Windows, and containerized Gateway deployments. For cross-network discovery, the same
-beacon can also be published through a configured wide-area DNS-SD domain. Discovery
-is still best-effort and does **not** replace SSH or Tailnet-based connectivity.
-
-## Wide-area Bonjour (Unicast DNS-SD) over Tailscale
-
-If the node and gateway are on different networks, multicast mDNS won't cross the
-boundary. You can keep the same discovery UX by switching to **unicast DNS-SD**
-("Wide-Area Bonjour") over Tailscale.
-
-High-level steps:
-
-1. Run a DNS server on the gateway host (reachable over Tailnet).
-2. Publish DNS-SD records for `_fengming-gw._tcp` under a dedicated zone
-   (example: `fengming.internal.`).
-3. Configure Tailscale **split DNS** so your chosen domain resolves via that
-   DNS server for clients (including iOS).
-
-FengMing supports any discovery domain; `fengming.internal.` is just an example.
-iOS/Android nodes browse both `local.` and your configured wide-area domain.
-
-### Gateway config (recommended)
-
-```json5
-{
-  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
-  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
-}
-```
-
-### One-time DNS server setup (gateway host)
-
-```bash
-fengming dns setup --apply
-```
-
-This installs CoreDNS and configures it to:
-
-- listen on port 53 only on the gateway's Tailscale interfaces
-- serve your chosen domain (example: `fengming.internal.`) from `~/.fengming/dns/<domain>.db`
-
-Validate from a tailnet-connected machine:
-
-```bash
-dns-sd -B _fengming-gw._tcp fengming.internal.
-dig @<TAILNET_IPV4> -p 53 _fengming-gw._tcp.fengming.internal PTR +short
-```
-
-### Tailscale DNS settings
-
-In the Tailscale admin console:
-
-- Add a nameserver pointing at the gateway's tailnet IP (UDP/TCP 53).
-- Add split DNS so your discovery domain uses that nameserver.
-
-Once clients accept tailnet DNS, iOS nodes and CLI discovery can browse
-`_fengming-gw._tcp` in your discovery domain without multicast.
-
-### Gateway listener security (recommended)
-
-The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tailnet
-access, bind explicitly and keep auth enabled.
-
-For tailnet-only setups:
-
-- Set `gateway.bind: "tailnet"` in `~/.fengming/fengming.json`.
-- Restart the Gateway (or restart the macOS menubar app).
-
-## What advertises
-
-Only the Gateway advertises `_fengming-gw._tcp`. LAN multicast advertising is
-provided by the bundled `bonjour` plugin when the plugin is enabled; wide-area
-DNS-SD publishing remains Gateway-owned.
-
-## Service types
-
-- `_fengming-gw._tcp` - gateway transport beacon (used by macOS/iOS/Android nodes).
-
-## TXT keys (non-secret hints)
-
-The Gateway advertises small non-secret hints to make UI flows convenient:
-
-- `role=gateway`
-- `displayName=<friendly name>`
-- `lanHost=<hostname>.local`
-- `gatewayPort=<port>` (Gateway WS + HTTP)
-- `gatewayTls=1` (only when TLS is enabled)
-- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
-- `canvasPort=<port>` (only when the canvas host is enabled; currently the same as `gatewayPort`)
-- `transport=gateway`
-- `tailnetDns=<magicdns>` (mDNS full mode only, optional hint when Tailnet is available)
-- `sshPort=<port>` (full mode only; omitted in minimal and off modes)
-- `cliPath=<path>` (full mode only; omitted in minimal and off modes)
-
-Security notes:
-
-- Bonjour/mDNS TXT records are **unauthenticated**. Clients must not treat TXT as authoritative routing.
-- Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat `lanHost`, `tailnetDns`, `gatewayPort`, and `gatewayTlsSha256` as hints only.
-- SSH auto-targeting should likewise use the resolved service host, not TXT-only hints.
-- TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
-- iOS/Android nodes should treat discovery-based direct connects as **TLS-only** and require explicit user confirmation before trusting a first-time fingerprint.
-
-## Debugging on macOS
-
-Useful built-in tools:
-
-- Browse instances:
-
-  ```bash
-  dns-sd -B _fengming-gw._tcp local.
-  ```
-
-- Resolve one instance (replace `<instance>`):
-
-  ```bash
-  dns-sd -L "<instance>" _fengming-gw._tcp local.
-  ```
-
-If browsing works but resolving fails, you're usually hitting a LAN policy or
-mDNS resolver issue.
-
-## Debugging in Gateway logs
-
-The Gateway writes a rolling log file (printed on startup as
-`gateway log file: ...`). Look for `bonjour:` lines, especially:
-
-- `bonjour: advertise failed ...`
-- `bonjour: suppressing ciao cancellation ...`
-- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
-- `bonjour: watchdog detected non-announced service ...`
-- `bonjour: disabling advertiser after ... failed restarts ...`
-
-The watchdog treats active `probing`, `announcing`, and fresh conflict-renames as
-in-progress states. If the service never reaches `announced`, FengMing eventually
-recreates the advertiser and, after repeated failures, disables Bonjour for that
-Gateway process instead of re-advertising forever.
-
-Bonjour uses the system hostname for the advertised `.local` host when it is a
-valid DNS label. If the system hostname contains spaces, underscores, or another
-invalid DNS-label character, FengMing falls back to `fengming.local`. Set
-`FENGMING_MDNS_HOSTNAME=<name>` before starting the Gateway when you need an
-explicit host label.
-
-## Debugging on iOS node
-
-The iOS node uses `NWBrowser` to discover `_fengming-gw._tcp`.
-
-To capture logs:
-
-- Settings → Gateway → Advanced → **Discovery Debug Logs**
-- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**
-
-The log includes browser state transitions and result-set changes.
-
-## When to enable Bonjour
-
-Bonjour auto-starts for empty-config Gateway startup on macOS hosts because the
-local app and nearby iOS/Android nodes commonly rely on same-LAN discovery.
-
-Enable Bonjour explicitly when same-LAN auto-discovery is useful on Linux,
-Windows, or another non-macOS host:
-
-```bash
-fengming plugins enable bonjour
-```
-
-When enabled, Bonjour uses `discovery.mdns.mode` to decide how much TXT metadata
-to publish. The same mode controls optional TXT hints in wide-area DNS-SD records.
-The default mode is `minimal`; use `full` only when clients need `cliPath` or
-`sshPort` hints. Use `off` to suppress LAN multicast without changing plugin
-enablement; wide-area DNS-SD can still publish the minimal Gateway beacon when
-`discovery.wideArea.enabled` is true.
-
-## When to disable Bonjour
-
-Leave Bonjour disabled when LAN multicast advertising is unnecessary, unavailable,
-or harmful. The common cases are non-macOS servers, Docker bridge networking,
-WSL, or a network policy that drops mDNS multicast. In those environments the
-Gateway is still reachable through its published URL, SSH, Tailnet, or wide-area
-DNS-SD, but LAN auto-discovery is not reliable.
-
-Prefer the existing environment override when the problem is deployment-scoped:
-
-```bash
-FENGMING_DISABLE_BONJOUR=1
-```
-
-That disables LAN multicast advertising without changing plugin configuration.
-It is safe for Docker images, service files, launch scripts, and one-off
-debugging because the setting disappears when the environment does.
-
-Use plugin configuration when you intentionally want to turn off the bundled LAN
-discovery plugin for that FengMing config:
-
-```bash
-fengming plugins disable bonjour
-```
-
-## Docker gotchas
-
-The bundled Bonjour plugin auto-disables LAN multicast advertising in detected
-containers when `FENGMING_DISABLE_BONJOUR` is unset. Docker bridge networks
-usually do not forward mDNS multicast (`224.0.0.251:5353`) between the container
-and the LAN, so advertising from the container rarely makes discovery work.
-
-Important gotchas:
-
-- Bonjour auto-starts on macOS hosts and is opt-in elsewhere. Leaving it
-  disabled does not stop the Gateway; it only skips LAN multicast advertising.
-- Disabling Bonjour does not change `gateway.bind`; Docker still defaults to
-  `FENGMING_GATEWAY_BIND=lan` so the published host port can work.
-- Disabling Bonjour does not disable wide-area DNS-SD. Use wide-area discovery
-  or Tailnet when the Gateway and node are not on the same LAN.
-- Reusing the same `FENGMING_CONFIG_DIR` outside Docker does not persist the
-  container auto-disable policy.
-- Set `FENGMING_DISABLE_BONJOUR=0` only for host networking, macvlan, or another
-  network where mDNS multicast is known to pass; set it to `1` to force-disable.
-
-## Troubleshooting disabled Bonjour
-
-If a node no longer auto-discovers the Gateway after Docker setup:
-
-1. Confirm whether the Gateway is running in auto, forced-on, or forced-off mode:
-
-   ```bash
-   docker compose config | grep FENGMING_DISABLE_BONJOUR
-   ```
-
-2. Confirm the Gateway itself is reachable through the published port:
-
-   ```bash
-   curl -fsS http://127.0.0.1:18789/healthz
-   ```
-
-3. Use a direct target when Bonjour is disabled:
-   - Control UI or local tools: `http://127.0.0.1:18789`
-   - LAN clients: `http://<gateway-host>:18789`
-   - Cross-network clients: Tailnet MagicDNS, Tailnet IP, SSH tunnel, or
-     wide-area DNS-SD
-
-4. If you deliberately enabled the Bonjour plugin in Docker and forced advertising
-   with `FENGMING_DISABLE_BONJOUR=0`, test multicast from the host:
-
-   ```bash
-   dns-sd -B _fengming-gw._tcp local.
-   ```
-
-   If browsing is empty or the Gateway logs show repeated ciao watchdog
-   cancellations, restore `FENGMING_DISABLE_BONJOUR=1` and use a direct or
-   Tailnet route.
-
-## Common failure modes
-
-- **Bonjour doesn't cross networks**: use Tailnet or SSH.
-- **Multicast blocked**: some Wi-Fi networks disable mDNS.
-- **Advertiser stuck in probing/announcing**: hosts with blocked multicast,
-  container bridges, WSL, or interface churn can leave the ciao advertiser in a
-  non-announced state. FengMing retries a few times and then disables Bonjour
-  for the current Gateway process instead of restarting the advertiser forever.
-- **Docker bridge networking**: Bonjour auto-disables in detected containers.
-  Set `FENGMING_DISABLE_BONJOUR=0` only for host, macvlan, or another
-  mDNS-capable network.
-- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
-- **Browse works but resolve fails**: keep machine names simple (avoid emojis or
-  punctuation), then restart the Gateway. The service instance name derives from
-  the host name, so overly complex names can confuse some resolvers.
-
-## Escaped instance names (`\032`)
-
-Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\DDD`
-sequences (e.g. spaces become `\032`).
-
-- This is normal at the protocol level.
-- UIs should decode for display (iOS uses `BonjourEscapes.decode`).
-
-## Enabling / disabling / configuration
-
-- macOS hosts auto-start the bundled LAN discovery plugin by default.
-- `fengming plugins enable bonjour` enables the bundled LAN discovery plugin on hosts where it is not default-enabled.
-- `fengming plugins disable bonjour` disables LAN multicast advertising by disabling the bundled plugin.
-- `FENGMING_DISABLE_BONJOUR=1` disables LAN multicast advertising without changing plugin config; accepted truthy values are `1`, `true`, `yes`, and `on` (legacy: `FENGMING_DISABLE_BONJOUR`).
-- `FENGMING_DISABLE_BONJOUR=0` forces LAN multicast advertising on, including inside detected containers; accepted falsy values are `0`, `false`, `no`, and `off`.
-- When the Bonjour plugin is enabled and `FENGMING_DISABLE_BONJOUR` is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers.
-- `gateway.bind` in `~/.fengming/fengming.json` controls the Gateway bind mode.
-- `FENGMING_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `FENGMING_SSH_PORT`).
-- `FENGMING_TAILNET_DNS` publishes a MagicDNS hint in TXT when mDNS full mode is enabled (legacy: `FENGMING_TAILNET_DNS`).
-- `FENGMING_CLI_PATH` overrides the advertised CLI path (legacy: `FENGMING_CLI_PATH`).
-
-## Related docs
-
-- Discovery policy and transport selection: [Discovery](/gateway/discovery)
-- Node pairing + approvals: [Gateway pairing](/gateway/pairing)

package/docs/gateway/bridge-protocol.md

@@ -1,97 +0,0 @@
----
-summary: "Historical bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
-read_when:
-  - Building or debugging node clients (iOS/Android/macOS node mode)
-  - Investigating pairing or bridge auth failures
-  - Auditing the node surface exposed by the gateway
-title: "Bridge protocol"
----
-
-<Warning>
-The TCP bridge has been **removed**. Current FengMing builds do not ship the bridge listener and `bridge.*` config keys are no longer in the schema. This page is kept for historical reference only. Use the [Gateway Protocol](/gateway/protocol) for all node/operator clients.
-</Warning>
-
-## Why it existed
-
-- **Security boundary**: the bridge exposes a small allowlist instead of the
-  full gateway API surface.
-- **Pairing + node identity**: node admission is owned by the gateway and tied
-  to a per-node token.
-- **Discovery UX**: nodes can discover gateways via Bonjour on LAN, or connect
-  directly over a tailnet.
-- **Loopback WS**: the full WS control plane stays local unless tunneled via SSH.
-
-## Transport
-
-- TCP, one JSON object per line (JSONL).
-- Optional TLS (when `bridge.tls.enabled` is true).
-- Historical default listener port was `18790` (current builds do not start a
-  TCP bridge).
-
-When TLS is enabled, discovery TXT records include `bridgeTls=1` plus
-`bridgeTlsSha256` as a non-secret hint. Note that Bonjour/mDNS TXT records are
-unauthenticated; clients must not treat the advertised fingerprint as an
-authoritative pin without explicit user intent or other out-of-band verification.
-
-## Handshake + pairing
-
-1. Client sends `hello` with node metadata + token (if already paired).
-2. If not paired, gateway replies `error` (`NOT_PAIRED`/`UNAUTHORIZED`).
-3. Client sends `pair-request`.
-4. Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
-
-Historically, `hello-ok` returned `serverName`; hosted plugin surfaces are now
-advertised through `pluginSurfaceUrls`. Canvas/A2UI uses
-`pluginSurfaceUrls.canvas`; the deprecated `canvasHostUrl` alias is not part of
-the refactored protocol.
-
-## Frames
-
-Client → Gateway:
-
-- `req` / `res`: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
-- `event`: node signals (voice transcript, agent request, chat subscribe, exec lifecycle)
-
-Gateway → Client:
-
-- `invoke` / `invoke-res`: node commands (`canvas.*`, `camera.*`, `screen.record`,
-  `location.get`, `sms.send`)
-- `event`: chat updates for subscribed sessions
-- `ping` / `pong`: keepalive
-
-Legacy allowlist enforcement lived in `src/gateway/server-bridge.ts` (removed).
-
-## Exec lifecycle events
-
-Nodes can emit `exec.finished` events to surface completed `system.run` activity.
-These are mapped to system events in the gateway. (Legacy nodes may still emit `exec.started`.)
-Nodes may emit `exec.denied` for denied `system.run` attempts; the gateway accepts
-the event as a terminal denial and does not enqueue a system event or wake agent work.
-
-Payload fields (all optional unless noted):
-
-- `sessionKey` (required): agent session for event correlation and, for
-  `exec.finished`, system event delivery.
-- `runId`: unique exec id for grouping.
-- `command`: raw or formatted command string.
-- `exitCode`, `timedOut`, `success`, `output`: completion details (finished only).
-- `reason`: denial reason (denied only).
-
-## Historical tailnet usage
-
-- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
-  `~/.fengming/fengming.json` (historical only; `bridge.*` is no longer valid).
-- Clients connect via MagicDNS name or tailnet IP.
-- Bonjour does **not** cross networks; use manual host/port or wide-area DNS-SD
-  when needed.
-
-## Versioning
-
-The bridge was **implicit v1** (no min/max negotiation). This section is
-historical reference only; current node/operator clients use the WebSocket
-[Gateway Protocol](/gateway/protocol).
-
-## Related
-
-- [Gateway protocol](/gateway/protocol)
-- [Nodes](/nodes)