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/<publicId>/<provider>`
> - `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://<ingress-host>`. Do
not add `<ingress-host>` to `PAPERCLIP_ALLOWED_HOSTNAMES`.
3. Send `POST
https://<ingress-host>/api/chat-webhooks/<publicId>/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/<publicId>/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 <noreply@anthropic.com>
This commit is contained in:
Eldar PolitkinandClaude Opus 5.5 authored and GitHub committed 2026-11-16 14:52:44 -06:00
1 parent c8dd2e400f
commit b298f5ce1d
1 file changed
+1 -1
+1 -1
View File
@@ -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/<runId>`; 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. |