fengming 0.3.9 → 0.3.11

package/docs/gateway/security/audit-checks.md

@@ -1,127 +0,0 @@
----
-summary: "Reference catalog of checkIds emitted by fengming security audit"
-read_when:
-  - You saw a specific `checkId` in `fengming security audit` output and want to know what it means
-  - You need the fix key/path for a given finding
-  - You are triaging severity across a security audit run
-title: "Security audit checks"
----
-
-`fengming security audit` emits structured findings keyed by `checkId`. This
-page is the reference catalog for those IDs. For the high-level threat model
-and hardening guidance, see [Security](/gateway/security).
-
-High-signal `checkId` values you will most likely see in real deployments (not
-exhaustive):
-
-| `checkId`                                                     | Severity      | Why it matters                                                                       | Primary fix key/path                                                                                 | Auto-fix |
-| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -------- |
-| `fs.state_dir.perms_world_writable`                           | critical      | Other users/processes can modify full FengMing state                                 | filesystem perms on `~/.fengming`                                                                    | yes      |
-| `fs.state_dir.perms_group_writable`                           | warn          | Group users can modify full FengMing state                                           | filesystem perms on `~/.fengming`                                                                    | yes      |
-| `fs.state_dir.perms_readable`                                 | warn          | State dir is readable by others                                                      | filesystem perms on `~/.fengming`                                                                    | yes      |
-| `fs.state_dir.symlink`                                        | warn          | State dir target becomes another trust boundary                                      | state dir filesystem layout                                                                          | no       |
-| `fs.config.perms_writable`                                    | critical      | Others can change auth/tool policy/config                                            | filesystem perms on `~/.fengming/fengming.json`                                                      | yes      |
-| `fs.config.symlink`                                           | warn          | Symlinked config files are unsupported for writes and add another trust boundary     | replace with a regular config file or point `FENGMING_CONFIG_PATH` at the real file                  | no       |
-| `fs.config.perms_group_readable`                              | warn          | Group users can read config tokens/settings                                          | filesystem perms on config file                                                                      | yes      |
-| `fs.config.perms_world_readable`                              | critical      | Config can expose tokens/settings                                                    | filesystem perms on config file                                                                      | yes      |
-| `fs.config_include.perms_writable`                            | critical      | Config include file can be modified by others                                        | include-file perms referenced from `fengming.json`                                                   | yes      |
-| `fs.config_include.perms_group_readable`                      | warn          | Group users can read included secrets/settings                                       | include-file perms referenced from `fengming.json`                                                   | yes      |
-| `fs.config_include.perms_world_readable`                      | critical      | Included secrets/settings are world-readable                                         | include-file perms referenced from `fengming.json`                                                   | yes      |
-| `fs.auth_profiles.perms_writable`                             | critical      | Others can inject or replace stored model credentials                                | `agents/<agentId>/agent/auth-profiles.json` perms                                                    | yes      |
-| `fs.auth_profiles.perms_readable`                             | warn          | Others can read API keys and OAuth tokens                                            | `agents/<agentId>/agent/auth-profiles.json` perms                                                    | yes      |
-| `fs.credentials_dir.perms_writable`                           | critical      | Others can modify channel pairing/credential state                                   | filesystem perms on `~/.fengming/credentials`                                                        | yes      |
-| `fs.credentials_dir.perms_readable`                           | warn          | Others can read channel credential state                                             | filesystem perms on `~/.fengming/credentials`                                                        | yes      |
-| `fs.sessions_store.perms_readable`                            | warn          | Others can read session transcripts/metadata                                         | session store perms                                                                                  | yes      |
-| `fs.log_file.perms_readable`                                  | warn          | Others can read redacted-but-still-sensitive logs                                    | gateway log file perms                                                                               | yes      |
-| `fs.synced_dir`                                               | warn          | State/config in iCloud/Dropbox/Drive broadens token/transcript exposure              | move config/state off synced folders                                                                 | no       |
-| `gateway.bind_no_auth`                                        | critical      | Remote bind without shared secret                                                    | `gateway.bind`, `gateway.auth.*`                                                                     | no       |
-| `gateway.loopback_no_auth`                                    | critical      | Reverse-proxied loopback may become unauthenticated                                  | `gateway.auth.*`, proxy setup                                                                        | no       |
-| `gateway.trusted_proxies_missing`                             | warn          | Reverse-proxy headers are present but not trusted                                    | `gateway.trustedProxies`                                                                             | no       |
-| `gateway.http.no_auth`                                        | warn/critical | Gateway HTTP APIs reachable with `auth.mode="none"`                                  | `gateway.auth.mode`, `gateway.http.endpoints.*`, `plugins.entries.admin-http-rpc`                    | no       |
-| `gateway.http.session_key_override_enabled`                   | info          | HTTP API callers can override `sessionKey`                                           | `gateway.http.allowSessionKeyOverride`                                                               | no       |
-| `gateway.tools_invoke_http.dangerous_allow`                   | warn/critical | Re-enables dangerous tools over HTTP API                                             | `gateway.tools.allow`                                                                                | no       |
-| `gateway.nodes.allow_commands_dangerous`                      | warn/critical | Enables high-impact node commands (camera/screen/contacts/calendar/SMS)              | `gateway.nodes.allowCommands`                                                                        | no       |
-| `gateway.nodes.deny_commands_ineffective`                     | warn          | Pattern-like deny entries do not match shell text or groups                          | `gateway.nodes.denyCommands`                                                                         | no       |
-| `gateway.tailscale_funnel`                                    | critical      | Public internet exposure                                                             | `gateway.tailscale.mode`                                                                             | no       |
-| `gateway.tailscale_serve`                                     | info          | Tailnet exposure is enabled via Serve                                                | `gateway.tailscale.mode`                                                                             | no       |
-| `gateway.control_ui.allowed_origins_required`                 | critical      | Non-loopback Control UI without explicit browser-origin allowlist                    | `gateway.controlUi.allowedOrigins`                                                                   | no       |
-| `gateway.control_ui.allowed_origins_wildcard`                 | warn/critical | `allowedOrigins=["*"]` disables browser-origin allowlisting                          | `gateway.controlUi.allowedOrigins`                                                                   | no       |
-| `gateway.control_ui.host_header_origin_fallback`              | warn/critical | Enables Host-header origin fallback (DNS rebinding hardening downgrade)              | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback`                                         | no       |
-| `gateway.control_ui.insecure_auth`                            | warn          | Insecure-auth compatibility toggle enabled                                           | `gateway.controlUi.allowInsecureAuth`                                                                | no       |
-| `gateway.control_ui.device_auth_disabled`                     | critical      | Disables device identity check                                                       | `gateway.controlUi.dangerouslyDisableDeviceAuth`                                                     | no       |
-| `gateway.real_ip_fallback_enabled`                            | warn/critical | Trusting `X-Real-IP` fallback can enable source-IP spoofing via proxy misconfig      | `gateway.allowRealIpFallback`, `gateway.trustedProxies`                                              | no       |
-| `gateway.token_too_short`                                     | warn          | Short shared token is easier to brute force                                          | `gateway.auth.token`                                                                                 | no       |
-| `gateway.auth_no_rate_limit`                                  | warn          | Exposed auth without rate limiting increases brute-force risk                        | `gateway.auth.rateLimit`                                                                             | no       |
-| `gateway.trusted_proxy_auth`                                  | critical      | Proxy identity now becomes the auth boundary                                         | `gateway.auth.mode="trusted-proxy"`                                                                  | no       |
-| `gateway.trusted_proxy_no_proxies`                            | critical      | Trusted-proxy auth without trusted proxy IPs is unsafe                               | `gateway.trustedProxies`                                                                             | no       |
-| `gateway.trusted_proxy_no_user_header`                        | critical      | Trusted-proxy auth cannot resolve user identity safely                               | `gateway.auth.trustedProxy.userHeader`                                                               | no       |
-| `gateway.trusted_proxy_no_allowlist`                          | warn          | Trusted-proxy auth accepts any authenticated upstream user                           | `gateway.auth.trustedProxy.allowUsers`                                                               | no       |
-| `gateway.trusted_proxy_allow_loopback`                        | warn          | Trusted-proxy auth accepts explicitly allowed loopback proxy sources                 | `gateway.auth.trustedProxy.allowLoopback`                                                            | no       |
-| `gateway.probe_auth_secretref_unavailable`                    | warn          | Deep probe could not resolve auth SecretRefs in this command path                    | deep-probe auth source / SecretRef availability                                                      | no       |
-| `gateway.probe_failed`                                        | warn/critical | Live Gateway probe failed                                                            | gateway reachability/auth                                                                            | no       |
-| `discovery.mdns_full_mode`                                    | warn/critical | mDNS full mode advertises `cliPath`/`sshPort` metadata on local network              | `discovery.mdns.mode`, `gateway.bind`                                                                | no       |
-| `config.insecure_or_dangerous_flags`                          | warn          | One insecure/dangerous debug flag is enabled                                         | key named in finding detail                                                                          | no       |
-| `security.audit.suppressions.active`                          | info          | Audit output has configured suppressions and may be filtered                         | `security.audit.suppressions`                                                                        | no       |
-| `config.secrets.gateway_password_in_config`                   | warn          | Gateway password is stored directly in config                                        | `gateway.auth.password`                                                                              | no       |
-| `config.secrets.hooks_token_in_config`                        | warn          | Hook bearer token is stored directly in config                                       | `hooks.token`                                                                                        | no       |
-| `hooks.token_reuse_gateway_token`                             | critical      | Hook ingress token also unlocks Gateway auth                                         | `hooks.token`, `gateway.auth.token`, `gateway.auth.password`                                         | no       |
-| `hooks.token_too_short`                                       | warn          | Easier brute force on hook ingress                                                   | `hooks.token`                                                                                        | no       |
-| `hooks.default_session_key_unset`                             | warn          | Hook agent runs fan out into generated per-request sessions                          | `hooks.defaultSessionKey`                                                                            | no       |
-| `hooks.allowed_agent_ids_unrestricted`                        | warn/critical | Authenticated hook callers may route to any configured agent                         | `hooks.allowedAgentIds`                                                                              | no       |
-| `hooks.request_session_key_enabled`                           | warn/critical | External caller can choose sessionKey                                                | `hooks.allowRequestSessionKey`                                                                       | no       |
-| `hooks.request_session_key_prefixes_missing`                  | warn/critical | No bound on external session key shapes                                              | `hooks.allowedSessionKeyPrefixes`                                                                    | no       |
-| `hooks.path_root`                                             | critical      | Hook path is `/`, making ingress easier to collide or misroute                       | `hooks.path`                                                                                         | no       |
-| `hooks.installs_unpinned_npm_specs`                           | warn          | Hook install records are not pinned to immutable npm specs                           | hook install metadata                                                                                | no       |
-| `hooks.installs_missing_integrity`                            | warn          | Hook install records lack integrity metadata                                         | hook install metadata                                                                                | no       |
-| `hooks.installs_version_drift`                                | warn          | Hook install records drift from installed packages                                   | hook install metadata                                                                                | no       |
-| `logging.redact_off`                                          | warn          | Sensitive values leak to logs/status                                                 | `logging.redactSensitive`                                                                            | yes      |
-| `browser.control_invalid_config`                              | warn          | Browser control config is invalid before runtime                                     | `browser.*`                                                                                          | no       |
-| `browser.control_no_auth`                                     | critical      | Browser control exposed without token/password auth                                  | `gateway.auth.*`                                                                                     | no       |
-| `browser.remote_cdp_http`                                     | warn          | Remote CDP over plain HTTP lacks transport encryption                                | browser profile `cdpUrl`                                                                             | no       |
-| `browser.remote_cdp_private_host`                             | warn          | Remote CDP targets a private/internal host                                           | browser profile `cdpUrl`, `browser.ssrfPolicy.*`                                                     | no       |
-| `sandbox.docker_config_mode_off`                              | warn          | Sandbox Docker config present but inactive                                           | `agents.*.sandbox.mode`                                                                              | no       |
-| `sandbox.bind_mount_non_absolute`                             | warn          | Relative bind mounts can resolve unpredictably                                       | `agents.*.sandbox.docker.binds[]`                                                                    | no       |
-| `sandbox.dangerous_bind_mount`                                | critical      | Sandbox bind mount targets blocked system, credential, or Docker socket paths        | `agents.*.sandbox.docker.binds[]`                                                                    | no       |
-| `sandbox.dangerous_network_mode`                              | critical      | Sandbox Docker network uses `host` or `container:*` namespace-join mode              | `agents.*.sandbox.docker.network`                                                                    | no       |
-| `sandbox.dangerous_seccomp_profile`                           | critical      | Sandbox seccomp profile weakens container isolation                                  | `agents.*.sandbox.docker.securityOpt`                                                                | no       |
-| `sandbox.dangerous_apparmor_profile`                          | critical      | Sandbox AppArmor profile weakens container isolation                                 | `agents.*.sandbox.docker.securityOpt`                                                                | no       |
-| `sandbox.browser_cdp_bridge_unrestricted`                     | warn          | Sandbox browser bridge is exposed without source-range restriction                   | `sandbox.browser.cdpSourceRange`                                                                     | no       |
-| `sandbox.browser_container.non_loopback_publish`              | critical      | Existing browser container publishes CDP on non-loopback interfaces                  | browser sandbox container publish config                                                             | no       |
-| `sandbox.browser_container.hash_label_missing`                | warn          | Existing browser container predates current config-hash labels                       | `fengming sandbox recreate --browser --all`                                                          | no       |
-| `sandbox.browser_container.hash_epoch_stale`                  | warn          | Existing browser container predates current browser config epoch                     | `fengming sandbox recreate --browser --all`                                                          | no       |
-| `tools.exec.host_sandbox_no_sandbox_defaults`                 | warn          | `exec host=sandbox` fails closed when sandbox is off                                 | `tools.exec.host`, `agents.defaults.sandbox.mode`                                                    | no       |
-| `tools.exec.host_sandbox_no_sandbox_agents`                   | warn          | Per-agent `exec host=sandbox` fails closed when sandbox is off                       | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode`                                        | no       |
-| `tools.exec.security_full_configured`                         | warn/critical | Host exec is running with `security="full"`                                          | `tools.exec.security`, `agents.list[].tools.exec.security`                                           | no       |
-| `tools.exec.fs_tools_disabled_but_exec_enabled`               | warn          | Filesystem tool policy does not make shell execution read-only                       | `tools.deny`, `agents.list[].tools.deny`, `agents.*.sandbox.workspaceAccess`                         | no       |
-| `tools.exec.auto_allow_skills_enabled`                        | warn          | Exec approvals trust skill bins implicitly                                           | `~/.fengming/exec-approvals.json`                                                                    | no       |
-| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn          | Interpreter allowlists permit inline eval without forced reapproval                  | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, exec approvals allowlist | no       |
-| `tools.exec.safe_bins_interpreter_unprofiled`                 | warn          | Interpreter/runtime bins in `safeBins` without explicit profiles broaden exec risk   | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*`                    | no       |
-| `tools.exec.safe_bins_broad_behavior`                         | warn          | Broad-behavior tools in `safeBins` weaken the low-risk stdin-filter trust model      | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins`                                           | no       |
-| `tools.exec.safe_bin_trusted_dirs_risky`                      | warn          | `safeBinTrustedDirs` includes mutable or risky directories                           | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs`                       | no       |
-| `skills.workspace.symlink_escape`                             | warn          | Workspace `skills/**/SKILL.md` resolves outside workspace root (symlink-chain drift) | workspace `skills/**` filesystem state                                                               | no       |
-| `plugins.extensions_no_allowlist`                             | warn          | Plugins are installed without an explicit plugin allowlist                           | `plugins.allowlist`                                                                                  | no       |
-| `plugins.installs_unpinned_npm_specs`                         | warn          | Plugin index records are not pinned to immutable npm specs                           | plugin install metadata                                                                              | no       |
-| `plugins.installs_missing_integrity`                          | warn          | Plugin index records lack integrity metadata                                         | plugin install metadata                                                                              | no       |
-| `plugins.installs_version_drift`                              | warn          | Plugin index records drift from installed packages                                   | plugin install metadata                                                                              | no       |
-| `plugins.code_safety`                                         | warn/critical | Plugin code scan found suspicious or dangerous patterns                              | plugin code / install source                                                                         | no       |
-| `plugins.code_safety.entry_path`                              | warn          | Plugin entry path points into hidden or `node_modules` locations                     | plugin manifest `entry`                                                                              | no       |
-| `plugins.code_safety.entry_escape`                            | critical      | Plugin entry escapes the plugin directory                                            | plugin manifest `entry`                                                                              | no       |
-| `plugins.code_safety.scan_failed`                             | warn          | Plugin code scan could not complete                                                  | plugin path / scan environment                                                                       | no       |
-| `skills.code_safety`                                          | warn/critical | Skill installer metadata/code contains suspicious or dangerous patterns              | skill install source                                                                                 | no       |
-| `skills.code_safety.scan_failed`                              | warn          | Skill code scan could not complete                                                   | skill scan environment                                                                               | no       |
-| `security.exposure.open_channels_with_exec`                   | warn/critical | Shared/public rooms can reach exec-enabled agents                                    | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*`        | no       |
-| `security.exposure.open_groups_with_elevated`                 | critical      | Open groups + elevated tools create high-impact prompt-injection paths               | `channels.*.groupPolicy`, `tools.elevated.*`                                                         | no       |
-| `security.exposure.open_groups_with_runtime_or_fs`            | critical/warn | Open groups can reach command/file tools without sandbox/workspace guards            | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode`    | no       |
-| `security.trust_model.multi_user_heuristic`                   | warn          | Config looks multi-user while gateway trust model is personal-assistant              | split trust boundaries, or shared-user hardening (`sandbox.mode`, tool deny/workspace scoping`)      | no       |
-| `tools.profile_minimal_overridden`                            | warn          | Agent overrides bypass global minimal profile                                        | `agents.list[].tools.profile`                                                                        | no       |
-| `plugins.tools_reachable_permissive_policy`                   | warn          | Extension tools reachable in permissive contexts                                     | `tools.profile` + tool allow/deny                                                                    | no       |
-| `models.legacy`                                               | warn          | Legacy model families are still configured                                           | model selection                                                                                      | no       |
-| `models.weak_tier`                                            | warn          | Configured models are below current recommended tiers                                | model selection                                                                                      | no       |
-| `models.small_params`                                         | critical/info | Small models + unsafe tool surfaces raise injection risk                             | model choice + sandbox/tool policy                                                                   | no       |
-| `summary.attack_surface`                                      | info          | Roll-up summary of auth, channel, tool, and exposure posture                         | multiple keys (see finding detail)                                                                   | no       |
-
-## Related
-
-- [Security](/gateway/security)
-- [Configuration](/gateway/configuration)
-- [Trusted proxy auth](/gateway/trusted-proxy-auth)

package/docs/gateway/security/exposure-runbook.md

@@ -1,212 +0,0 @@
----
-summary: "Pre-flight and rollback checklist before exposing an FengMing Gateway beyond loopback"
-title: "Gateway exposure runbook"
-sidebarTitle: "Exposure runbook"
-read_when:
-  - Exposing the Gateway over LAN, tailnet, Tailscale Serve, Funnel, or a reverse proxy
-  - Reviewing a deployment before allowing real messaging users
-  - Rolling back a risky remote access or DM configuration
----
-
-<Warning>
-Expose the Gateway only after you can explain who can reach it, how they are
-authenticated, which agents they can trigger, and which tools those agents can
-use. When in doubt, return to loopback-only access and re-run the audit.
-</Warning>
-
-This runbook turns the broader [Security](/gateway/security) guidance into an
-operator checklist for remote access and messaging exposure.
-
-## Choose the exposure pattern
-
-Prefer the narrowest pattern that satisfies the workflow.
-
-| Pattern                    | Recommended when                                | Required controls                                                                                   |
-| -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| Loopback + SSH tunnel      | Personal use, admin access, debugging           | Keep `gateway.bind: "loopback"` and tunnel `127.0.0.1:18789`                                        |
-| Loopback + Tailscale Serve | Personal tailnet access to Control UI/WebSocket | Keep Gateway loopback-only; rely on Tailscale identity headers only for supported surfaces          |
-| Tailnet/LAN bind           | Dedicated private network with known devices    | Gateway auth, firewall allowlist, no public port-forward                                            |
-| Trusted reverse proxy      | Organization SSO/OIDC in front of Gateway       | `trusted-proxy` auth, strict `trustedProxies`, header overwrite/strip rules, explicit allowed users |
-| Public internet            | Rare, high-risk deployments                     | Identity-aware proxy, TLS, rate limits, strict allowlists, sandboxed non-main sessions              |
-
-Avoid direct public port-forwarding to the Gateway. If you need public access,
-put an identity-aware proxy in front of it and make the proxy the only network
-path to the Gateway.
-
-## Pre-flight inventory
-
-Record these before changing bind, proxy, Tailscale, or channel policy:
-
-- Gateway host, OS user, and state directory.
-- Gateway URL and bind mode.
-- Auth mode, token/password source, or trusted proxy identity source.
-- All enabled channels and whether they accept DMs, groups, or webhooks.
-- Agents reachable from non-local senders.
-- Tool profile, sandbox mode, and elevated tool policy for each reachable agent.
-- External credentials available to those agents.
-- Backup location for `~/.fengming/fengming.json` and credentials.
-
-If more than one person can message the bot, treat this as shared delegated tool
-authority, not as per-user host isolation.
-
-## Baseline checks
-
-Run these before opening access:
-
-```bash
-fengming doctor
-fengming security audit
-fengming security audit --deep
-fengming health
-```
-
-Resolve critical findings first. Warnings may be acceptable only when they are
-intentional and documented for the deployment.
-
-For remote CLI validation, pass credentials explicitly:
-
-```bash
-fengming gateway probe --url ws://127.0.0.1:18789 --token "$FENGMING_GATEWAY_TOKEN"
-```
-
-Do not assume local config credentials apply to an explicit remote URL.
-
-## Minimum safe baseline
-
-Use this shape as the starting point for exposed deployments:
-
-```json5
-{
-  gateway: {
-    bind: "loopback",
-    auth: {
-      mode: "token",
-      token: "replace-with-a-long-random-token",
-    },
-  },
-  session: {
-    dmScope: "per-channel-peer",
-  },
-  agents: {
-    defaults: {
-      sandbox: { mode: "non-main" },
-    },
-  },
-  tools: {
-    profile: "messaging",
-    exec: { security: "deny", ask: "always" },
-    elevated: { enabled: false },
-  },
-}
-```
-
-Then widen one control at a time. For example, add a specific channel allowlist
-before enabling write-capable tools, or enable a reverse proxy before accepting
-remote Control UI traffic.
-
-The strict `exec.security: "deny"` baseline blocks all exec calls, including
-benign diagnostics. If diagnostics or low-risk commands are required, relax this
-only after choosing the specific senders, agents, commands, and approval mode
-that match your threat model.
-
-## DM and group exposure
-
-Messaging channels are untrusted input surfaces. Before allowing DMs or groups:
-
-- Prefer `dmPolicy: "pairing"` or strict `allowFrom` lists.
-- Avoid `dmPolicy: "open"` unless every sender is trusted.
-- Do not combine `"*"` allowlists with broad tool access.
-- Require mentions in groups unless the room is tightly controlled.
-- Use `session.dmScope: "per-channel-peer"` when multiple people can DM the bot.
-- Route shared channels to agents with minimal tools and no personal credentials.
-
-Pairing approves the sender to trigger the bot. It does not make that sender a
-separate host security boundary.
-
-## Reverse proxy checks
-
-For identity-aware proxies:
-
-- The proxy must authenticate users before forwarding to the Gateway.
-- Direct access to the Gateway port must be blocked by firewall or network policy.
-- `gateway.trustedProxies` must contain only the proxy source IPs.
-- The proxy must strip or overwrite client-supplied identity and forwarding headers.
-- `gateway.auth.trustedProxy.allowUsers` should list expected users when the proxy serves more than one audience.
-- Same-host loopback proxy mode should use `allowLoopback` only when local processes are trusted and the proxy owns the identity headers.
-
-Run `fengming security audit --deep` after proxy changes. Trusted-proxy findings
-are intentionally high-signal because the proxy becomes the authentication
-boundary.
-
-## Tool and sandbox review
-
-Before exposing an agent to remote senders:
-
-- Confirm which sessions run on host versus sandbox.
-- Deny or require approval for host exec.
-- Keep elevated tools disabled unless a specific, trusted sender needs them.
-- Avoid browser, canvas, node, cron, gateway, and session-spawn tools for open or semi-open messaging surfaces.
-- Keep bind mounts narrow and avoid credential, home, Docker socket, and system paths.
-- Use separate gateways, OS users, or hosts for materially different trust boundaries.
-
-If remote users are not fully trusted, isolation must come from separate
-deployments, not only from prompts or session labels.
-
-## Post-change validation
-
-After each exposure change:
-
-1. Re-run `fengming security audit --deep`.
-2. Test a successful authorized connection.
-3. Test that an unauthorized sender or browser session is denied.
-4. Confirm logs redact secrets.
-5. Confirm DM/group routing reaches only the intended agent.
-6. Confirm high-impact tools ask for approval or are denied.
-7. Document the accepted residual warnings.
-
-Do not proceed to the next exposure change until the current one is understood.
-
-## Rollback plan
-
-If the Gateway may be overexposed:
-
-```json5
-{
-  gateway: {
-    bind: "loopback",
-  },
-  channels: {
-    whatsapp: { dmPolicy: "disabled" },
-    telegram: { dmPolicy: "disabled" },
-    discord: { dmPolicy: "disabled" },
-    slack: { dmPolicy: "disabled" },
-  },
-  tools: {
-    exec: { security: "deny", ask: "always" },
-    elevated: { enabled: false },
-  },
-}
-```
-
-Then:
-
-1. Stop public forwarding, Tailscale Funnel, or reverse proxy routes.
-2. Rotate Gateway tokens/passwords and affected integration credentials.
-3. Remove `"*"` and unexpected senders from allowlists.
-4. Review recent audit logs, run history, tool calls, and config changes.
-5. Re-run `fengming security audit --deep`.
-6. Re-enable access with the narrowest pattern that satisfies the workflow.
-
-## Review checklist
-
-- Gateway remains loopback-only unless there is a documented reason.
-- Non-loopback access has auth, firewalling, and no public direct route.
-- Trusted-proxy deployments have strict proxy IPs and header controls.
-- DMs use pairing or allowlists, not open access by default.
-- Groups require mentions or explicit allowlists.
-- Shared channels do not reach personal credentials.
-- Non-main sessions run in sandbox mode.
-- Host exec and elevated tools are denied or approval-gated.
-- Logs redact secrets.
-- Critical audit findings are resolved.
-- Rollback steps are tested and documented.