fengming 0.3.9 → 0.3.11

package/docs/channels/nextcloud-talk.md

@@ -1,176 +0,0 @@
----
-summary: "Nextcloud Talk support status, capabilities, and configuration"
-read_when:
-  - Working on Nextcloud Talk channel features
-title: "Nextcloud Talk"
----
-
-Status: bundled plugin (webhook bot). Direct messages, rooms, reactions, and markdown messages are supported.
-
-## Bundled plugin
-
-Nextcloud Talk ships as a bundled plugin in current FengMing releases, so
-normal packaged builds do not need a separate install.
-
-If you are on an older build or a custom install that excludes Nextcloud Talk,
-install the npm package directly:
-
-Install via CLI (npm registry):
-
-```bash
-fengming plugins install @fengming/nextcloud-talk
-```
-
-Use the bare package to follow the current official release tag. Pin an exact
-version only when you need a reproducible install.
-
-Local checkout (when running from a git repo):
-
-```bash
-fengming plugins install ./path/to/local/nextcloud-talk-plugin
-```
-
-Details: [Plugins](/tools/plugin)
-
-## Quick setup (beginner)
-
-1. Ensure the Nextcloud Talk plugin is available.
-   - Current packaged FengMing releases already bundle it.
-   - Older/custom installs can add it manually with the commands above.
-2. On your Nextcloud server, create a bot:
-
-   ```bash
-   ./occ talk:bot:install "FengMing" "<shared-secret>" "<webhook-url>" --feature webhook --feature response --feature reaction
-   ```
-
-3. Enable the bot in the target room settings.
-4. Configure FengMing:
-   - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
-   - Or env: `NEXTCLOUD_TALK_BOT_SECRET` (default account only)
-
-   CLI setup:
-
-   ```bash
-   fengming channels add --channel nextcloud-talk \
-     --url https://cloud.example.com \
-     --token "<shared-secret>"
-   ```
-
-   Equivalent explicit fields:
-
-   ```bash
-   fengming channels add --channel nextcloud-talk \
-     --base-url https://cloud.example.com \
-     --secret "<shared-secret>"
-   ```
-
-   File-backed secret:
-
-   ```bash
-   fengming channels add --channel nextcloud-talk \
-     --base-url https://cloud.example.com \
-     --secret-file /path/to/nextcloud-talk-secret
-   ```
-
-5. Restart the gateway (or finish setup).
-
-Minimal config:
-
-```json5
-{
-  channels: {
-    "nextcloud-talk": {
-      enabled: true,
-      baseUrl: "https://cloud.example.com",
-      botSecret: "shared-secret",
-      dmPolicy: "pairing",
-    },
-  },
-}
-```
-
-## Notes
-
-- Bots cannot initiate DMs. The user must message the bot first.
-- Webhook URL must be reachable by the Gateway; set `webhookPublicUrl` if behind a proxy.
-- Media uploads are not supported by the bot API; media is sent as URLs.
-- The webhook payload does not distinguish DMs vs rooms; set `apiUser` + `apiPassword` to enable room-type lookups (otherwise DMs are treated as rooms).
-
-## Access control (DMs)
-
-- Default: `channels.nextcloud-talk.dmPolicy = "pairing"`. Unknown senders get a pairing code.
-- Approve via:
-  - `fengming pairing list nextcloud-talk`
-  - `fengming pairing approve nextcloud-talk <CODE>`
-- Public DMs: `channels.nextcloud-talk.dmPolicy="open"` plus `channels.nextcloud-talk.allowFrom=["*"]`.
-- `allowFrom` matches Nextcloud user IDs only; display names are ignored.
-
-## Rooms (groups)
-
-- Default: `channels.nextcloud-talk.groupPolicy = "allowlist"` (mention-gated).
-- Allowlist rooms with `channels.nextcloud-talk.rooms`:
-
-```json5
-{
-  channels: {
-    "nextcloud-talk": {
-      rooms: {
-        "room-token": { requireMention: true },
-      },
-    },
-  },
-}
-```
-
-- To allow no rooms, keep the allowlist empty or set `channels.nextcloud-talk.groupPolicy="disabled"`.
-
-## Capabilities
-
-| Feature         | Status        |
-| --------------- | ------------- |
-| Direct messages | Supported     |
-| Rooms           | Supported     |
-| Threads         | Not supported |
-| Media           | URL-only      |
-| Reactions       | Supported     |
-| Native commands | Not supported |
-
-## Configuration reference (Nextcloud Talk)
-
-Full configuration: [Configuration](/gateway/configuration)
-
-Provider options:
-
-- `channels.nextcloud-talk.enabled`: enable/disable channel startup.
-- `channels.nextcloud-talk.baseUrl`: Nextcloud instance URL.
-- `channels.nextcloud-talk.botSecret`: bot shared secret.
-- `channels.nextcloud-talk.botSecretFile`: regular-file secret path. Symlinks are rejected.
-- `channels.nextcloud-talk.apiUser`: API user for room lookups (DM detection).
-- `channels.nextcloud-talk.apiPassword`: API/app password for room lookups.
-- `channels.nextcloud-talk.apiPasswordFile`: API password file path.
-- `channels.nextcloud-talk.webhookPort`: webhook listener port (default: 8788).
-- `channels.nextcloud-talk.webhookHost`: webhook host (default: 0.0.0.0).
-- `channels.nextcloud-talk.webhookPath`: webhook path (default: /nextcloud-talk-webhook).
-- `channels.nextcloud-talk.webhookPublicUrl`: externally reachable webhook URL.
-- `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`.
-- `channels.nextcloud-talk.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`.
-- `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`.
-- `channels.nextcloud-talk.groupAllowFrom`: group allowlist (user IDs).
-- `channels.nextcloud-talk.rooms`: per-room settings and allowlist.
-- Static sender access groups can be referenced from `allowFrom` and `groupAllowFrom` with `accessGroup:<name>`.
-- `channels.nextcloud-talk.historyLimit`: group history limit (0 disables).
-- `channels.nextcloud-talk.dmHistoryLimit`: DM history limit (0 disables).
-- `channels.nextcloud-talk.dms`: per-DM overrides (historyLimit).
-- `channels.nextcloud-talk.textChunkLimit`: outbound text chunk size (chars).
-- `channels.nextcloud-talk.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
-- `channels.nextcloud-talk.blockStreaming`: disable block streaming for this channel.
-- `channels.nextcloud-talk.blockStreamingCoalesce`: block streaming coalesce tuning.
-- `channels.nextcloud-talk.mediaMaxMb`: inbound media cap (MB).
-
-## Related
-
-- [Channels Overview](/channels) — all supported channels
-- [Pairing](/channels/pairing) — DM authentication and pairing flow
-- [Groups](/channels/groups) — group chat behavior and mention gating
-- [Channel Routing](/channels/channel-routing) — session routing for messages
-- [Security](/gateway/security) — access model and hardening

package/docs/channels/nostr.md

@@ -1,253 +0,0 @@
----
-summary: "Nostr DM channel via NIP-04 encrypted messages"
-read_when:
-  - You want FengMing to receive DMs via Nostr
-  - You're setting up decentralized messaging
-title: "Nostr"
----
-
-**Status:** Optional bundled plugin (disabled by default until configured).
-
-Nostr is a decentralized protocol for social networking. This channel enables FengMing to receive and respond to encrypted direct messages (DMs) via NIP-04.
-
-## Bundled plugin
-
-Current FengMing releases ship Nostr as a bundled plugin, so normal packaged
-builds do not need a separate install.
-
-### Older/custom installs
-
-- Onboarding (`fengming onboard`) and `fengming channels add` still surface
-  Nostr from the shared channel catalog.
-- If your build excludes bundled Nostr, install the npm package directly.
-
-```bash
-fengming plugins install @fengming/nostr
-```
-
-Use the bare package to follow the current official release tag. Pin an exact
-version only when you need a reproducible install.
-
-Use a local checkout (dev workflows):
-
-```bash
-fengming plugins install --link <path-to-local-nostr-plugin>
-```
-
-Restart the Gateway after installing or enabling plugins.
-
-### Non-interactive setup
-
-```bash
-fengming channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
-fengming channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"
-```
-
-Use `--use-env` to keep `NOSTR_PRIVATE_KEY` in the environment instead of storing the key in config.
-
-## Quick setup
-
-1. Generate a Nostr keypair (if needed):
-
-```bash
-# Using nak
-nak key generate
-```
-
-2. Add to config:
-
-```json5
-{
-  channels: {
-    nostr: {
-      privateKey: "${NOSTR_PRIVATE_KEY}",
-    },
-  },
-}
-```
-
-3. Export the key:
-
-```bash
-export NOSTR_PRIVATE_KEY="nsec1..."
-```
-
-4. Restart the Gateway.
-
-## Configuration reference
-
-| Key          | Type     | Default                                     | Description                         |
-| ------------ | -------- | ------------------------------------------- | ----------------------------------- |
-| `privateKey` | string   | required                                    | Private key in `nsec` or hex format |
-| `relays`     | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | Relay URLs (WebSocket)              |
-| `dmPolicy`   | string   | `pairing`                                   | DM access policy                    |
-| `allowFrom`  | string[] | `[]`                                        | Allowed sender pubkeys              |
-| `enabled`    | boolean  | `true`                                      | Enable/disable channel              |
-| `name`       | string   | -                                           | Display name                        |
-| `profile`    | object   | -                                           | NIP-01 profile metadata             |
-
-## Profile metadata
-
-Profile data is published as a NIP-01 `kind:0` event. You can manage it from the Control UI (Channels -> Nostr -> Profile) or set it directly in config.
-
-Example:
-
-```json5
-{
-  channels: {
-    nostr: {
-      privateKey: "${NOSTR_PRIVATE_KEY}",
-      profile: {
-        name: "fengming",
-        displayName: "FengMing",
-        about: "Personal assistant DM bot",
-        picture: "https://example.com/avatar.png",
-        banner: "https://example.com/banner.png",
-        website: "https://example.com",
-        nip05: "fengming@example.com",
-        lud16: "fengming@example.com",
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- Profile URLs must use `https://`.
-- Importing from relays merges fields and preserves local overrides.
-
-## Access control
-
-### DM policies
-
-- **pairing** (default): unknown senders get a pairing code.
-- **allowlist**: only pubkeys in `allowFrom` can DM.
-- **open**: public inbound DMs (requires `allowFrom: ["*"]`).
-- **disabled**: ignore inbound DMs.
-
-Enforcement notes:
-
-- Inbound event signatures are verified before sender policy and NIP-04 decryption, so forged events are rejected early.
-- Pairing replies are sent without processing the original DM body.
-- Inbound DMs are rate-limited and oversized payloads are dropped before decrypt.
-
-### Allowlist example
-
-```json5
-{
-  channels: {
-    nostr: {
-      privateKey: "${NOSTR_PRIVATE_KEY}",
-      dmPolicy: "allowlist",
-      allowFrom: ["npub1abc...", "npub1xyz..."],
-    },
-  },
-}
-```
-
-## Key formats
-
-Accepted formats:
-
-- **Private key:** `nsec...` or 64-char hex
-- **Pubkeys (`allowFrom`):** `npub...` or hex
-
-## Relays
-
-Defaults: `relay.damus.io` and `nos.lol`.
-
-```json5
-{
-  channels: {
-    nostr: {
-      privateKey: "${NOSTR_PRIVATE_KEY}",
-      relays: ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"],
-    },
-  },
-}
-```
-
-Tips:
-
-- Use 2-3 relays for redundancy.
-- Avoid too many relays (latency, duplication).
-- Paid relays can improve reliability.
-- Local relays are fine for testing (`ws://localhost:7777`).
-
-## Protocol support
-
-| NIP    | Status    | Description                           |
-| ------ | --------- | ------------------------------------- |
-| NIP-01 | Supported | Basic event format + profile metadata |
-| NIP-04 | Supported | Encrypted DMs (`kind:4`)              |
-| NIP-17 | Planned   | Gift-wrapped DMs                      |
-| NIP-44 | Planned   | Versioned encryption                  |
-
-## Testing
-
-### Local relay
-
-```bash
-# Start strfry
-docker run -p 7777:7777 ghcr.io/hoytech/strfry
-```
-
-```json5
-{
-  channels: {
-    nostr: {
-      privateKey: "${NOSTR_PRIVATE_KEY}",
-      relays: ["ws://localhost:7777"],
-    },
-  },
-}
-```
-
-### Manual test
-
-1. Note the bot pubkey (npub) from logs.
-2. Open a Nostr client (Damus, Amethyst, etc.).
-3. DM the bot pubkey.
-4. Verify the response.
-
-## Troubleshooting
-
-### Not receiving messages
-
-- Verify the private key is valid.
-- Ensure relay URLs are reachable and use `wss://` (or `ws://` for local).
-- Confirm `enabled` is not `false`.
-- Check Gateway logs for relay connection errors.
-
-### Not sending responses
-
-- Check relay accepts writes.
-- Verify outbound connectivity.
-- Watch for relay rate limits.
-
-### Duplicate responses
-
-- Expected when using multiple relays.
-- Messages are deduplicated by event ID; only the first delivery triggers a response.
-
-## Security
-
-- Never commit private keys.
-- Use environment variables for keys.
-- Consider `allowlist` for production bots.
-- Signatures are verified before sender policy, and sender policy is enforced before decrypt, so forged events are rejected early and unknown senders cannot force full crypto work.
-
-## Limitations (MVP)
-
-- Direct messages only (no group chats).
-- No media attachments.
-- NIP-04 only (NIP-17 gift-wrap planned).
-
-## Related
-
-- [Channels Overview](/channels) — all supported channels
-- [Pairing](/channels/pairing) — DM authentication and pairing flow
-- [Groups](/channels/groups) — group chat behavior and mention gating
-- [Channel Routing](/channels/channel-routing) — session routing for messages
-- [Security](/gateway/security) — access model and hardening

package/docs/channels/pairing.md

@@ -1,214 +0,0 @@
----
-summary: "Pairing overview: approve who can DM you + which nodes can join"
-read_when:
-  - Setting up DM access control
-  - Pairing a new iOS/Android node
-  - Reviewing FengMing security posture
-title: "Pairing"
----
-
-"Pairing" is FengMing's explicit access approval step.
-It is used in two places:
-
-1. **DM pairing** (who is allowed to talk to the bot)
-2. **Node pairing** (which devices/nodes are allowed to join the gateway network)
-
-Security context: [Security](/gateway/security)
-
-## 1) DM pairing (inbound chat access)
-
-When a channel is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
-
-Default DM policies are documented in: [Security](/gateway/security)
-
-`dmPolicy: "open"` is public only when the effective DM allowlist includes `"*"`.
-Setup and validation require that wildcard for public-open configs. If existing
-state contains `open` with concrete `allowFrom` entries, runtime still admits
-only those senders, and pairing-store approvals do not widen `open` access.
-
-Pairing codes:
-
-- 8 characters, uppercase, no ambiguous chars (`0O1I`).
-- **Expire after 1 hour**. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
-- Pending DM pairing requests are capped at **3 per channel** by default; additional requests are ignored until one expires or is approved.
-
-### Approve a sender
-
-```bash
-fengming pairing list telegram
-fengming pairing approve telegram <CODE>
-```
-
-If no command owner is configured yet, approving a DM pairing code also bootstraps
-`commands.ownerAllowFrom` to the approved sender, such as `telegram:123456789`.
-That gives first-time setups an explicit owner for privileged commands and exec
-approval prompts. After an owner exists, later pairing approvals only grant DM
-access; they do not add more owners.
-
-Supported channels: `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `fengming-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`.
-
-### Reusable sender groups
-
-Use top-level `accessGroups` when the same trusted sender set should apply to
-multiple message channels or to both DM and group allowlists.
-
-Static groups use `type: "message.senders"` and are referenced with
-`accessGroup:<name>` from channel allowlists:
-
-```json5
-{
-  accessGroups: {
-    operators: {
-      type: "message.senders",
-      members: {
-        discord: ["discord:123456789012345678"],
-        telegram: ["987654321"],
-        whatsapp: ["+15551234567"],
-      },
-    },
-  },
-  channels: {
-    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
-    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
-  },
-}
-```
-
-Access groups are documented in detail here: [Access groups](/channels/access-groups)
-
-### Where the state lives
-
-Stored under `~/.fengming/credentials/`:
-
-- Pending requests: `<channel>-pairing.json`
-- Approved allowlist store:
-  - Default account: `<channel>-allowFrom.json`
-  - Non-default account: `<channel>-<accountId>-allowFrom.json`
-
-Account scoping behavior:
-
-- Non-default accounts read/write only their scoped allowlist file.
-- Default account uses the channel-scoped unscoped allowlist file.
-
-Treat these as sensitive (they gate access to your assistant).
-
-<Note>
-The pairing allowlist store is for DM access. Group authorization is separate.
-Approving a DM pairing code does not automatically allow that sender to run group
-commands or control the bot in groups. First-owner bootstrap is separate config
-state in `commands.ownerAllowFrom`, and group chat delivery still follows the
-channel's group allowlists (for example `groupAllowFrom`, `groups`, or per-group
-or per-topic overrides depending on the channel).
-</Note>
-
-## 2) Node device pairing (iOS/Android/macOS/headless nodes)
-
-Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
-creates a device pairing request that must be approved.
-
-### Pair via Telegram (recommended for iOS)
-
-If you use the `device-pair` plugin, you can do first-time device pairing entirely from Telegram:
-
-1. In Telegram, message your bot: `/pair`
-2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram).
-3. On your phone, open the FengMing iOS app → Settings → Gateway.
-4. Scan the QR code or paste the setup code and connect.
-5. Back in Telegram: `/pair pending` (review request IDs, role, and scopes), then approve.
-
-The setup code is a base64-encoded JSON payload that contains:
-
-- `url`: the Gateway WebSocket URL (`ws://...` or `wss://...`)
-- `bootstrapToken`: a short-lived single-device bootstrap token used for the initial pairing handshake
-
-That bootstrap token carries the built-in pairing bootstrap profile:
-
-- the built-in setup profile allows the fresh QR/setup-code baseline only:
-  `node` plus a bounded `operator` handoff
-- the handed-off `node` token stays `scopes: []`
-- the handed-off `operator` token is limited to `operator.approvals`,
-  `operator.read`, and `operator.write`
-- `operator.admin` and `operator.pairing` are not granted by QR/setup-code
-  bootstrap; they require a separate approved operator pairing or token flow
-- later token rotation/revocation remains bounded by both the device's approved
-  role contract and the caller session's operator scopes
-
-Treat the setup code like a password while it is valid.
-
-For Tailscale, public, or other remote mobile pairing, use Tailscale Serve/Funnel
-or another `wss://` Gateway URL. Plaintext `ws://` setup codes are accepted only
-for loopback, private LAN addresses, `.local` Bonjour hosts, and the Android
-emulator host. Tailnet CGNAT addresses, `.ts.net` names, and public hosts still
-fail closed before QR/setup-code issuance.
-
-### Approve a node device
-
-```bash
-fengming devices list
-fengming devices approve <requestId>
-fengming devices reject <requestId>
-```
-
-When an explicit approval is denied because the approving paired-device session
-was opened with pairing-only scope, the CLI retries the same request with
-`operator.admin`. This lets an existing admin-capable paired device recover a new
-Control UI/browser pairing without editing `devices/paired.json` by hand. The
-Gateway still validates the retried connection; tokens that cannot authenticate
-with `operator.admin` remain blocked.
-
-If the same device retries with different auth details (for example different
-role/scopes/public key), the previous pending request is superseded and a new
-`requestId` is created.
-
-<Note>
-An already paired device does not get broader access silently. If it reconnects asking for more scopes or a broader role, FengMing keeps the existing approval as-is and creates a fresh pending upgrade request. Use `fengming devices list` to compare the currently approved access with the newly requested access before you approve.
-</Note>
-
-### Optional trusted-CIDR node auto-approve
-
-Device pairing remains manual by default. For tightly controlled node networks,
-you can opt in to first-time node auto-approval with explicit CIDRs or exact IPs:
-
-```json5
-{
-  gateway: {
-    nodes: {
-      pairing: {
-        autoApproveCidrs: ["192.168.1.0/24"],
-      },
-    },
-  },
-}
-```
-
-This only applies to fresh `role: node` pairing requests with no requested
-scopes. Operator, browser, Control UI, and WebChat clients still require manual
-approval. Role, scope, metadata, and public-key changes still require manual
-approval.
-
-### Node pairing state storage
-
-Stored under `~/.fengming/devices/`:
-
-- `pending.json` (short-lived; pending requests expire)
-- `paired.json` (paired devices + tokens)
-
-### Notes
-
-- The legacy `node.pair.*` API (CLI: `fengming nodes pending|approve|reject|remove|rename`) is a
-  separate gateway-owned pairing store. WS nodes still require device pairing.
-- The pairing record is the durable source of truth for approved roles. Active
-  device tokens stay bounded to that approved role set; a stray token entry
-  outside the approved roles does not create new access.
-
-## Related docs
-
-- Security model + prompt injection: [Security](/gateway/security)
-- Updating safely (run doctor): [Updating](/install/updating)
-- Channel configs:
-  - Telegram: [Telegram](/channels/telegram)
-  - WhatsApp: [WhatsApp](/channels/whatsapp)
-  - Signal: [Signal](/channels/signal)
-  - iMessage: [iMessage](/channels/imessage)
-  - Discord: [Discord](/channels/discord)
-  - Slack: [Slack](/channels/slack)