fengming 0.3.9 → 0.3.11

package/docs/gateway/security/secure-file-operations.md

@@ -1,76 +0,0 @@
----
-summary: "How FengMing handles local file access safely, and why the optional fs-safe Python helper is off by default"
-read_when:
-  - Changing file access, archive extraction, workspace storage, or plugin filesystem helpers
-title: "Secure file operations"
----
-
-FengMing uses [`@fengming/fs-safe`](https://github.com/fengming/fs-safe) for security-sensitive local file operations: root-bounded reads/writes, atomic replacement, archive extraction, temp workspaces, JSON state, and secret-file handling.
-
-The goal is a consistent **library guardrail** for trusted FengMing code that receives untrusted path names. It is not a sandbox. Host filesystem permissions, OS users, containers, and the agent/tool policy still define the real blast radius.
-
-## Default: no Python helper
-
-FengMing defaults the fs-safe POSIX Python helper to **off**.
-
-Why:
-
-- the gateway should not spawn a persistent Python sidecar unless an operator opted into it;
-- many installs do not need the extra parent-directory mutation hardening;
-- disabling Python keeps package/runtime behavior more predictable across desktop, Docker, CI, and bundled app environments.
-
-FengMing only changes the default. If you explicitly set a mode, fs-safe honors it:
-
-```bash
-# Default FengMing behavior: Node-only fs-safe fallbacks.
-FENGMING_FS_SAFE_PYTHON_MODE=off
-
-# Opt into the helper when available, falling back if unavailable.
-FENGMING_FS_SAFE_PYTHON_MODE=auto
-
-# Fail closed if the helper cannot start.
-FENGMING_FS_SAFE_PYTHON_MODE=require
-
-# Optional explicit interpreter.
-FENGMING_FS_SAFE_PYTHON=/usr/bin/python3
-```
-
-The generic fs-safe names also work: `FS_SAFE_PYTHON_MODE` and `FS_SAFE_PYTHON`.
-
-## What stays protected without Python
-
-With the helper off, FengMing still uses fs-safe's Node paths for:
-
-- rejecting relative-path escapes such as `..`, absolute paths, and path separators where only names are allowed;
-- resolving operations through a trusted root handle instead of ad-hoc `path.resolve(...).startsWith(...)` checks;
-- refusing symlink and hardlink patterns on APIs that require that policy;
-- opening files with identity checks where the API returns or consumes file contents;
-- atomic sibling-temp writes for state/config files;
-- byte limits for reads and archive extraction;
-- private modes for secrets and state files where the API requires them.
-
-These protections cover the normal FengMing threat model: trusted gateway code handling untrusted model/plugin/channel path input inside a single trusted operator boundary.
-
-## What Python adds
-
-On POSIX, fs-safe's optional helper keeps one persistent Python process and uses fd-relative filesystem operations for parent-directory mutations such as rename, remove, mkdir, stat/list, and some write paths.
-
-That narrows same-UID race windows where another process can swap a parent directory between validation and mutation. It is defense in depth for hosts where untrusted local processes can modify the same directories FengMing is operating in.
-
-If your deployment has that risk and Python is guaranteed to exist, use:
-
-```bash
-FENGMING_FS_SAFE_PYTHON_MODE=require
-```
-
-Use `require` rather than `auto` when the helper is part of your security posture; `auto` intentionally falls back to Node-only behavior if the helper is unavailable.
-
-## Plugin and core guidance
-
-- Plugin-facing file access should go through `fengming/plugin-sdk/*` helpers, not raw `fs`, when a path comes from a message, model output, config, or plugin input.
-- Core code should use the local fs-safe wrappers under `src/infra/*` so FengMing's process policy is applied consistently.
-- Archive extraction should use the fs-safe archive helpers with explicit size, entry-count, link, and destination limits.
-- Secrets should use FengMing secret helpers or fs-safe secret/private-state helpers; do not hand-roll mode checks around `fs.writeFile`.
-- If you need hostile local-user isolation, do not rely on fs-safe alone. Run separate gateways under separate OS users/hosts or use sandboxing.
-
-Related: [Security](/gateway/security), [Sandboxing](/gateway/sandboxing), [Exec approvals](/tools/exec-approvals), [Secrets](/gateway/secrets).

package/docs/gateway/security/shrinkwrap.md

@@ -1,111 +0,0 @@
----
-summary: "Plain-English and technical explanation of npm shrinkwrap in FengMing releases"
-read_when:
-  - You want to know what npm shrinkwrap means in an FengMing release
-  - You are reviewing package lockfiles, dependency changes, or supply-chain risk
-  - You are validating root or plugin npm packages before publishing
-title: "npm shrinkwrap"
----
-
-FengMing source checkouts use `pnpm-lock.yaml`. Published FengMing npm
-packages use `npm-shrinkwrap.json`, npm's publishable dependency lockfile, so
-package installs use the dependency graph reviewed during release.
-
-## The easy version
-
-Shrinkwrap is a receipt for the dependency tree that ships with an npm package.
-It tells npm which exact transitive package versions to install.
-
-For FengMing releases, that means:
-
-- the published package does not ask npm to invent a fresh dependency graph at
-  install time;
-- dependency changes become easier to review because they appear in a lockfile;
-- release validation can test the same graph users will install;
-- package-size or native-dependency surprises are easier to spot before
-  publishing.
-
-Shrinkwrap is not a sandbox. It does not make a dependency safe by itself, and
-it does not replace host isolation, `fengming security audit`, package
-provenance, or install smoke tests.
-
-The short mental model:
-
-| File                  | Where it matters         | What it means                     |
-| --------------------- | ------------------------ | --------------------------------- |
-| `pnpm-lock.yaml`      | FengMing source checkout | Maintainer dependency graph       |
-| `npm-shrinkwrap.json` | Published npm package    | npm install graph for users       |
-| `package-lock.json`   | Local npm apps           | Not the FengMing publish contract |
-
-## Why FengMing uses it
-
-FengMing is a gateway, plugin host, model router, and agent runtime. A default
-install can affect startup time, disk use, native package downloads, and
-supply-chain exposure.
-
-Shrinkwrap gives release review a stable boundary:
-
-- reviewers can see transitive dependency movement;
-- package validators can reject unexpected lockfile drift;
-- package acceptance can test installs with the graph that will ship;
-- plugin packages can carry their own locked dependency graph instead of
-  relying on the root package to own plugin-only dependencies.
-
-The goal is not "more lockfiles." The goal is reproducible release installs
-with clear ownership.
-
-## Technical details
-
-The root `fengming` npm package and FengMing-owned npm plugin packages include
-`npm-shrinkwrap.json` when they publish. Suitable FengMing-owned plugin
-packages can also publish with explicit `bundledDependencies`, so their runtime
-dependency files are carried in the plugin tarball instead of depending only on
-install-time resolution.
-
-Maintain the boundary like this:
-
-```bash
-pnpm deps:shrinkwrap:generate
-pnpm deps:shrinkwrap:check
-```
-
-The generator resolves npm's publishable lock format but rejects generated
-package versions that are not already present in `pnpm-lock.yaml`. That keeps
-the pnpm dependency age, override, and patch-review boundary intact.
-
-Use root-only commands only when intentionally refreshing the root package
-without touching plugin packages:
-
-```bash
-pnpm deps:shrinkwrap:root:generate
-pnpm deps:shrinkwrap:root:check
-```
-
-Review these files as security-sensitive:
-
-- `pnpm-lock.yaml`
-- `npm-shrinkwrap.json`
-- bundled plugin dependency payloads
-- any `package-lock.json` diff
-
-FengMing package validators require shrinkwrap in new root package tarballs.
-The plugin npm publish path checks plugin-local shrinkwrap, installs
-package-local bundled dependencies, and then packs or publishes. Package
-validators reject `package-lock.json` for published FengMing packages.
-
-To inspect a published root package:
-
-```bash
-npm pack fengming@<version> --json --pack-destination /tmp/fengming-pack
-tar -tf /tmp/fengming-pack/fengming-<version>.tgz | grep '^package/npm-shrinkwrap.json$'
-```
-
-To inspect an FengMing-owned plugin package:
-
-```bash
-npm pack @fengming/discord@<version> --json --pack-destination /tmp/fengming-plugin-pack
-tar -tf /tmp/fengming-plugin-pack/fengming-discord-<version>.tgz | grep '^package/npm-shrinkwrap.json$'
-tar -tf /tmp/fengming-plugin-pack/fengming-discord-<version>.tgz | grep '^package/node_modules/'
-```
-
-Background: [npm-shrinkwrap.json](https://docs.npmjs.com/cli/v11/configuring-npm/npm-shrinkwrap-json).

package/docs/gateway/tailscale.md

@@ -1,156 +0,0 @@
----
-summary: "Integrated Tailscale Serve/Funnel for the Gateway dashboard"
-read_when:
-  - Exposing the Gateway Control UI outside localhost
-  - Automating tailnet or public dashboard access
-title: "Tailscale"
----
-
-FengMing can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
-Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback while
-Tailscale provides HTTPS, routing, and (for Serve) identity headers.
-
-## Modes
-
-- `serve`: Tailnet-only Serve via `tailscale serve`. The gateway stays on `127.0.0.1`.
-- `funnel`: Public HTTPS via `tailscale funnel`. FengMing requires a shared password.
-- `off`: Default (no Tailscale automation).
-
-Status and audit output use **Tailscale exposure** for this FengMing Serve/Funnel
-mode. `off` means FengMing is not managing Serve or Funnel; it does not mean the
-local Tailscale daemon is stopped or logged out.
-
-## Auth
-
-Set `gateway.auth.mode` to control the handshake:
-
-- `none` (private ingress only)
-- `token` (default when `FENGMING_GATEWAY_TOKEN` is set)
-- `password` (shared secret via `FENGMING_GATEWAY_PASSWORD` or config)
-- `trusted-proxy` (identity-aware reverse proxy; see [Trusted Proxy Auth](/gateway/trusted-proxy-auth))
-
-When `tailscale.mode = "serve"` and `gateway.auth.allowTailscale` is `true`,
-Control UI/WebSocket auth can use Tailscale identity headers
-(`tailscale-user-login`) without supplying a token/password. FengMing verifies
-the identity by resolving the `x-forwarded-for` address via the local Tailscale
-daemon (`tailscale whois`) and matching it to the header before accepting it.
-FengMing only treats a request as Serve when it arrives from loopback with
-Tailscale's `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-host`
-headers.
-For Control UI operator sessions that include browser device identity, this
-verified Serve path also skips the device-pairing round trip. It does not bypass
-browser device identity: device-less clients are still rejected, and node-role
-or non-Control UI WebSocket connections still follow the normal pairing and
-auth checks.
-HTTP API endpoints (for example `/v1/*`, `/tools/invoke`, and `/api/channels/*`)
-do **not** use Tailscale identity-header auth. They still follow the gateway's
-normal HTTP auth mode: shared-secret auth by default, or an intentionally
-configured trusted-proxy / private-ingress `none` setup.
-This tokenless flow assumes the gateway host is trusted. If untrusted local code
-may run on the same host, disable `gateway.auth.allowTailscale` and require
-token/password auth instead.
-To require explicit shared-secret credentials, set `gateway.auth.allowTailscale: false`
-and use `gateway.auth.mode: "token"` or `"password"`.
-
-## Config examples
-
-### Tailnet-only (Serve)
-
-```json5
-{
-  gateway: {
-    bind: "loopback",
-    tailscale: { mode: "serve" },
-  },
-}
-```
-
-Open: `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
-
-### Tailnet-only (bind to Tailnet IP)
-
-Use this when you want the Gateway to listen directly on the Tailnet IP (no Serve/Funnel).
-
-```json5
-{
-  gateway: {
-    bind: "tailnet",
-    auth: { mode: "token", token: "your-token" },
-  },
-}
-```
-
-Connect from another Tailnet device:
-
-- Control UI: `http://<tailscale-ip>:18789/`
-- WebSocket: `ws://<tailscale-ip>:18789`
-
-<Note>
-Loopback (`http://127.0.0.1:18789`) will **not** work in this mode.
-</Note>
-
-### Public internet (Funnel + shared password)
-
-```json5
-{
-  gateway: {
-    bind: "loopback",
-    tailscale: { mode: "funnel" },
-    auth: { mode: "password", password: "replace-me" },
-  },
-}
-```
-
-Prefer `FENGMING_GATEWAY_PASSWORD` over committing a password to disk.
-
-## CLI examples
-
-```bash
-fengming gateway --tailscale serve
-fengming gateway --tailscale funnel --auth password
-```
-
-## Notes
-
-- Tailscale Serve/Funnel requires the `tailscale` CLI to be installed and logged in.
-- `tailscale.mode: "funnel"` refuses to start unless auth mode is `password` to avoid public exposure.
-- Set `gateway.tailscale.resetOnExit` if you want FengMing to undo `tailscale serve`
-  or `tailscale funnel` configuration on shutdown.
-- Set `gateway.tailscale.preserveFunnel: true` to keep an externally configured
-  `tailscale funnel` route alive across gateway restarts. When enabled and the
-  gateway runs in `mode: "serve"`, FengMing checks `tailscale funnel status`
-  before re-applying Serve and skips it when a Funnel route already covers the
-  gateway port. The FengMing-managed Funnel password-only policy is unchanged.
-- `gateway.bind: "tailnet"` is a direct Tailnet bind (no HTTPS, no Serve/Funnel).
-- `gateway.bind: "auto"` prefers loopback; use `tailnet` if you want Tailnet-only.
-- Serve/Funnel only expose the **Gateway control UI + WS**. Nodes connect over
-  the same Gateway WS endpoint, so Serve can work for node access.
-
-## Browser control (remote Gateway + local browser)
-
-If you run the Gateway on one machine but want to drive a browser on another machine,
-run a **node host** on the browser machine and keep both on the same tailnet.
-The Gateway will proxy browser actions to the node; no separate control server or Serve URL needed.
-
-Avoid Funnel for browser control; treat node pairing like operator access.
-
-## Tailscale prerequisites + limits
-
-- Serve requires HTTPS enabled for your tailnet; the CLI prompts if it is missing.
-- Serve injects Tailscale identity headers; Funnel does not.
-- Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and a funnel node attribute.
-- Funnel only supports ports `443`, `8443`, and `10000` over TLS.
-- Funnel on macOS requires the open-source Tailscale app variant.
-
-## Learn more
-
-- Tailscale Serve overview: [https://tailscale.com/kb/1312/serve](https://tailscale.com/kb/1312/serve)
-- `tailscale serve` command: [https://tailscale.com/kb/1242/tailscale-serve](https://tailscale.com/kb/1242/tailscale-serve)
-- Tailscale Funnel overview: [https://tailscale.com/kb/1223/tailscale-funnel](https://tailscale.com/kb/1223/tailscale-funnel)
-- `tailscale funnel` command: [https://tailscale.com/kb/1311/tailscale-funnel](https://tailscale.com/kb/1311/tailscale-funnel)
-
-## Related
-
-- [Remote access](/gateway/remote)
-- [Discovery](/gateway/discovery)
-- [Authentication](/gateway/authentication)

package/docs/gateway/tools-invoke-http-api.md

@@ -1,169 +0,0 @@
----
-summary: "Invoke a single tool directly via the Gateway HTTP endpoint"
-read_when:
-  - Calling tools without running a full agent turn
-  - Building automations that need tool policy enforcement
-title: "Tools invoke API"
----
-
-FengMing's Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled and uses Gateway auth plus tool policy. Like the OpenAI-compatible `/v1/*` surface, shared-secret bearer auth is treated as trusted operator access for the whole gateway.
-
-- `POST /tools/invoke`
-- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/tools/invoke`
-
-Default max payload size is 2 MB.
-
-## Authentication
-
-Uses the Gateway auth configuration.
-
-Common HTTP auth paths:
-
-- shared-secret auth (`gateway.auth.mode="token"` or `"password"`):
-  `Authorization: Bearer <token-or-password>`
-- trusted identity-bearing HTTP auth (`gateway.auth.mode="trusted-proxy"`):
-  route through the configured identity-aware proxy and let it inject the
-  required identity headers
-- private-ingress open auth (`gateway.auth.mode="none"`):
-  no auth header required
-
-Notes:
-
-- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `FENGMING_GATEWAY_TOKEN`).
-- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `FENGMING_GATEWAY_PASSWORD`).
-- When `gateway.auth.mode="trusted-proxy"`, the HTTP request must come from a
-  configured trusted proxy source; same-host loopback proxies require explicit
-  `gateway.auth.trustedProxy.allowLoopback = true`.
-- Internal same-host callers that bypass the proxy can use
-  `gateway.auth.password` / `FENGMING_GATEWAY_PASSWORD` as a local direct
-  fallback. Any `Forwarded`, `X-Forwarded-*`, or `X-Real-IP` header evidence
-  keeps the request on the trusted-proxy path instead.
-- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
-
-## Security boundary (important)
-
-Treat this endpoint as a **full operator-access** surface for the gateway instance.
-
-- HTTP bearer auth here is not a narrow per-user scope model.
-- A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
-- For shared-secret auth modes (`token` and `password`), the endpoint restores the normal full operator defaults even if the caller sends a narrower `x-fengming-scopes` header.
-- Shared-secret auth also treats direct tool invokes on this endpoint as owner-sender turns.
-- Trusted identity-bearing HTTP modes (for example trusted proxy auth or `gateway.auth.mode="none"` on a private ingress) honor `x-fengming-scopes` when present and otherwise fall back to the normal operator default scope set.
-- Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.
-
-Auth matrix:
-
-- `gateway.auth.mode="token"` or `"password"` + `Authorization: Bearer ...`
-  - proves possession of the shared gateway operator secret
-  - ignores narrower `x-fengming-scopes`
-  - restores the full default operator scope set:
-    `operator.admin`, `operator.approvals`, `operator.pairing`,
-    `operator.read`, `operator.talk.secrets`, `operator.write`
-  - treats direct tool invokes on this endpoint as owner-sender turns
-- trusted identity-bearing HTTP modes (for example trusted proxy auth, or `gateway.auth.mode="none"` on private ingress)
-  - authenticate some outer trusted identity or deployment boundary
-  - honor `x-fengming-scopes` when the header is present
-  - fall back to the normal operator default scope set when the header is absent
-  - only lose owner semantics when the caller explicitly narrows scopes and omits `operator.admin`
-
-## Request body
-
-```json
-{
-  "tool": "sessions_list",
-  "action": "json",
-  "args": {},
-  "sessionKey": "main",
-  "dryRun": false
-}
-```
-
-Fields:
-
-- `tool` (string, required): tool name to invoke.
-- `action` (string, optional): mapped into args if the tool schema supports `action` and the args payload omitted it.
-- `args` (object, optional): tool-specific arguments.
-- `sessionKey` (string, optional): target session key. If omitted or `"main"`, the Gateway uses the configured main session key (honors `session.mainKey` and default agent, or `global` in global scope).
-- `dryRun` (boolean, optional): reserved for future use; currently ignored.
-
-## Policy + routing behavior
-
-Tool availability is filtered through the same policy chain used by Gateway agents:
-
-- `tools.profile` / `tools.byProvider.profile`
-- `tools.allow` / `tools.byProvider.allow`
-- `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`
-- group policies (if the session key maps to a group or channel)
-- subagent policy (when invoking with a subagent session key)
-
-If a tool is not allowed by policy, the endpoint returns **404**.
-
-Important boundary notes:
-
-- Exec approvals are operator guardrails, not a separate authorization boundary for this HTTP endpoint. If a tool is reachable here via Gateway auth + tool policy, `/tools/invoke` does not add an extra per-call approval prompt.
-- If `exec` is reachable here, treat it as a mutating shell surface. Denying `write`, `edit`, `apply_patch`, or HTTP filesystem-write tools does not make shell execution read-only.
-- Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (and ideally separate OS users/hosts).
-
-Gateway HTTP also applies a hard deny list by default (even if session policy allows the tool):
-
-- `exec` - direct command execution (RCE surface)
-- `spawn` - arbitrary child process creation (RCE surface)
-- `shell` - shell command execution (RCE surface)
-- `fs_write` - arbitrary file mutation on the host
-- `fs_delete` - arbitrary file deletion on the host
-- `fs_move` - arbitrary file move/rename on the host
-- `apply_patch` - patch application can rewrite arbitrary files
-- `sessions_spawn` - session orchestration; spawning agents remotely is RCE
-- `sessions_send` - cross-session message injection
-- `cron` - persistent automation control plane
-- `gateway` - gateway control plane; prevents reconfiguration via HTTP
-- `nodes` - node command relay can reach system.run on paired hosts
-- `whatsapp_login` - interactive setup requiring terminal QR scan; hangs on HTTP
-
-You can customize this deny list via `gateway.tools`:
-
-```json5
-{
-  gateway: {
-    tools: {
-      // Additional tools to block over HTTP /tools/invoke
-      deny: ["browser"],
-      // Remove tools from the default deny list
-      allow: ["gateway"],
-    },
-  },
-}
-```
-
-To help group policies resolve context, you can optionally set:
-
-- `x-fengming-message-channel: <channel>` (example: `slack`, `telegram`)
-- `x-fengming-account-id: <accountId>` (when multiple accounts exist)
-
-## Responses
-
-- `200` → `{ ok: true, result }`
-- `400` → `{ ok: false, error: { type, message } }` (invalid request or tool input error)
-- `401` → unauthorized
-- `429` → auth rate-limited (`Retry-After` set)
-- `404` → tool not available (not found or not allowlisted)
-- `405` → method not allowed
-- `500` → `{ ok: false, error: { type, message } }` (unexpected tool execution error; sanitized message)
-
-## Example
-
-```bash
-curl -sS http://127.0.0.1:18789/tools/invoke \
-  -H 'Authorization: Bearer secret' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "tool": "sessions_list",
-    "action": "json",
-    "args": {}
-  }'
-```
-
-## Related
-
-- [Gateway protocol](/gateway/protocol)
-- [Tools and plugins](/tools)