From b298f5ce1dd4f2f3d82a8e41c517e4c1d8e581d9 Mon Sep 17 00:00:00 2001 From: Eldar Politkin <32969822+EldarPolitkin@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:52:44 +0200 Subject: [PATCH] docs: allow the chat webhook ingress hostname in private mode (#18301) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Native chat connectors receive provider webhooks at `/api/chat-webhooks//` > - `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` lets the webhook ingress use a different host than the board > - In `authenticated` + `private` mode, the private-hostname guard runs on every request, also on the webhook route > - The docs say that the ingress URL is not a trusted host. They do not say that the operator must allow the ingress hostname > - So a private instance behind a webhook-only tunnel answers 403 to every provider callback, and the operator gets no hint in the docs > - This pull request adds that step to the `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` row > - The benefit is that operators of private instances can connect Teams (or another webhook provider) without reading the guard source ## Linked Issues or Issue Description Refs #13468 (the next failure on the same path, after this step is done). Refs #15185. No issue exists for this docs gap. I searched open and closed issues and PRs for "hostname is not allowed webhook", "PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL", "private hostname guard webhook", "allowed-hostname tunnel 403" and "chat webhook 403". Only #14492 mentions the variable, and it is about Telegram long polling. **What happened?** Microsoft Teams callbacks through a webhook-only tunnel got `403 {"error":"This hostname is not allowed for this Paperclip instance. ..."}`. The request did not reach the Teams route. A `Host` rewrite at the tunnel did not help, because the guard reads `X-Forwarded-Host` first. **What did you expect?** The docs for `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` tell the operator to add the ingress hostname to `PAPERCLIP_ALLOWED_HOSTNAMES` in private mode. **Steps to reproduce** 1. Run `authenticated` mode with `private` exposure. 2. Set `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL=https://`. Do not add `` to `PAPERCLIP_ALLOWED_HOSTNAMES`. 3. Send `POST https:///api/chat-webhooks//microsoft-teams` through the tunnel. 4. The response is 403 from the private-hostname guard. **Paperclip version** v2026.1023.0 (Docker image), and the same code on `master`. **Deployment mode** `authenticated` + `private`, Docker, Postgres, Cloudflare tunnel that forwards only the Teams webhook path. ## What Changed - `docs/deploy/environment-variables.md`: the `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` row now tells private-mode operators to add the ingress hostname to `PAPERCLIP_ALLOWED_HOSTNAMES`. It also says that the guard reads `X-Forwarded-Host` before `Host`. ## Verification - Read the guard: `server/src/middleware/private-hostname-guard.ts` reads `x-forwarded-host` first, then `host`. `server/src/app.ts` mounts the guard for all routes, also `/api/chat-webhooks`. - Live check on our instance (v2026.1023.0, Microsoft 365 commercial tenant, Cloudflare tunnel): before the allowlist entry, `POST /api/chat-webhooks//microsoft-teams` returned 403 with the guard message. After we added the ingress hostname to `PAPERCLIP_ALLOWED_HOSTNAMES`, the same request reached the Teams route (`404 {"error":"Chat endpoint not found"}` for an unknown publicId). - `node scripts/check-forbidden-tokens.mjs`: `No forbidden tokens found.` - Docs-only change. No code or test change. ## Risks - Low risk. Docs only. No behavior change. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected - check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude, model ID `claude-opus-5-5` (Opus 5.5), in Claude Code. Tool use (shell, GitHub CLI) and code execution. Default reasoning mode. A human operator owns the Paperclip instance and the evidence. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Claude Opus 5.5 --- docs/deploy/environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deploy/environment-variables.md b/docs/deploy/environment-variables.md index 0460ab91346..70d804fc346 100644 --- a/docs/deploy/environment-variables.md +++ b/docs/deploy/environment-variables.md @@ -19,7 +19,7 @@ All environment variables that Paperclip uses for server configuration. | `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override | | `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` | | `PAPERCLIP_API_URL` | (auto-derived) | Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address. | -| `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` | (board public origin) | Optional HTTPS origin for native chat provider webhooks when ingress and the board use different hosts. Must have no credentials, path, query, or fragment; invalid configuration refuses startup. Used only for provider callback URLs, not board links, authentication, trusted hosts, or identity confirmation. | +| `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` | (board public origin) | Optional HTTPS origin for native chat provider webhooks when ingress and the board use different hosts. Must have no credentials, path, query, or fragment; invalid configuration refuses startup. Used only for provider callback URLs, not board links, authentication, trusted hosts, or identity confirmation. In `authenticated` mode with `private` exposure, also add the ingress hostname to `PAPERCLIP_ALLOWED_HOSTNAMES`. Otherwise the private-hostname guard rejects provider callbacks with 403 before they reach the webhook route. The guard reads `X-Forwarded-Host` before `Host`, so a reverse proxy that rewrites `Host` but forwards the original `X-Forwarded-Host` still gets 403. | | `PAPERCLIP_RUNNER_PUBLIC_URL` | (unset) | Explicit `wss://` base URL used only when a remote `paperclip_runner` target dials Paperclip directly. Paperclip appends `/api/runner/v1/connect/`; the reverse proxy must forward WebSocket upgrades for that route. This value is never inferred from request headers. Daytona ignores it and uses provider ingress. | | `PAPERCLIP_RUNNER_CA_BUNDLE_PATH` | (unset) | Optional PEM CA bundle for direct runner WSS. Platform roots remain enabled. There is no insecure TLS bypass. | | `PAPERCLIP_RUNNER_REMOTE_BINARY_PATH` | (host build) | Host-local path to a `paperclip-runnerd` artifact built for the remote target OS and architecture. Required when Paperclip and the remote sandbox do not share a compatible platform; build metadata and the required transport mode are verified before launch. |