[chbndrhnns]

Summary

Documents reverse-proxy deployment configurations for self-hosted instances calling /api/scenes.

Details

• Clarifies PASCAL_AUTH=proxy: when configured, /api/scenes accepts requests that reach Pascal without requiring an in-app session (meaning the app must be protected at the proxy level).
• Clarifies that PASCAL_AUTH=proxy is ignored when PASCAL_ADMIN_PASSWORD is configured, as password authentication takes precedence in resolveAuthMode.
• Documents reverse-proxy token injection: when protecting /api/scenes with PASCAL_SCENE_API_TOKEN behind a reverse proxy, the proxy should inject Authorization: Bearer <token> or X-Pascal-Scene-Token: <token> on forwarded requests.
• Documents PASCAL_SCENE_API_ORIGINS for CORS configuration.

---

Note

Low Risk
Comments and setup guide only; no application or auth logic changes.

Overview
Documentation-only update for self-hosted reverse-proxy and scene API setup in .env.example and SETUP.md.

.env.example adds commented guidance for proxy-injected scene API auth (Authorization or X-Pascal-Scene-Token), PASCAL_AUTH=proxy (with a note that it is ignored when PASCAL_ADMIN_PASSWORD is set), and PASCAL_SCENE_API_ORIGINS for CORS.

SETUP.md expands the env table and the self-hosting “Fail closed” section: in proxy mode /api/scenes trusts requests that reach the app (so exposure must be limited to the proxy), password auth wins over proxy mode, and proxies should inject the scene bearer when PASCAL_SCENE_API_TOKEN is used.

^{Reviewed by Cursor Bugbot for commit c1a155f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pascal]

I hit an error while handling your request (Model unavailable on AI Gateway free tier: Free tier users do not have access to this model. Upgrade to paid credits at https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up for unrestricted…).

Please try again, rephrase, or reach out if it keeps failing.

Error id: 5fd6ce60-1278-45c6-9c6c-9d3c5be88917

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 432381e. Configure here.}

[dkbbdev]

Verified this patch on a self-hosted deployment behind a Cloudflare Tunnel (no token, host is not loopback):

• Before: every /api/scenes call from the browser returned 503 {"error":"scene_api_token_required"} — the app was unusable behind the proxy (issue Browser scene creation returns 503 behind reverse proxy #878).
• After: with PASCAL_SCENE_API_ORIGINS=https://<host> set (and no PASCAL_SCENE_API_TOKEN), same-origin browser requests pass auth: scene list returns 200 and scene creation returns 201, verified end-to-end through the tunnel from an external network.

One deployment note from testing: both the http:// and https:// origin variants may be needed while a zone's cert is still provisioning, since browsers on plain http send the http origin. Might be worth a line in the README/env example.

Thanks for the fix — it unblocked our deployment.

[Aymericr]

Thanks for the clear repro, @chbndrhnns — the proxy 503 is a real problem for self-hosters. I can't merge this as is, though, because it opens an auth bypass:

• Origin and X-Forwarded-Host are both client-controlled. When PASCAL_SCENE_API_TOKEN is unset, any non-browser client can send Origin: https://pascal.example.com plus a matching X-Forwarded-Host and get full create/update/delete on the scene API. That's the same concern as Bugbot's high-severity finding — the follow-up commit fixed the parsing, but the trust problem is still there.
• Forwarded headers should only be honored behind an explicit opt-in (e.g. a PASCAL_TRUST_PROXY=1 env var), and even then I'd rather keep a configured token as the only non-loopback auth path. The simplest fix for your setup may be docs: set PASCAL_SCENE_API_TOKEN and have the proxy inject the header.
• Please also rebase onto current main.

Happy to re-review once it's reworked along those lines.

[chbndrhnns]

Thanks @Aymericr. Rebased onto current main (commit ee9adf1e).

Following your feedback and the recent commit 7607aeaa (apps/editor/lib/self-host-auth.ts), which introduced formal authentication modes (PASCAL_ADMIN_PASSWORD and PASCAL_AUTH=proxy):

1. Dropped the heuristic header-based bypass code completely so that Origin and X-Forwarded-Host are never used as authentication proof.
2. Updated SETUP.md and .env.example to document how to configure reverse-proxy deployments:
   • Use PASCAL_AUTH=proxy when an upstream proxy handles access control (which opens /api/scenes to authenticated browser sessions without a token).
   • Alternatively, set PASCAL_SCENE_API_TOKEN and have the reverse proxy inject the Authorization: Bearer <token> or X-Pascal-Scene-Token: <token> header on requests to /api/scenes.
   • Documented PASCAL_SCENE_API_ORIGINS for CORS configuration.

[Aymericr]

Thanks @chbndrhnns, dropping the header-based bypass and going docs-only is exactly the right call, and I checked that PASCAL_SCENE_API_ORIGINS and the X-Pascal-Scene-Token header both exist in apps/editor/lib/scene-api-security.ts. Two small things before this can go in:

1. The PASCAL_AUTH=proxy sentence in SETUP.md is a bit misleading. It says /api/scenes is "open to authenticated browser sessions", but in proxy mode there's no Pascal session at all: resolveAuthMode returns open, so with no PASCAL_SCENE_API_TOKEN set the scene API accepts every request that reaches the app. Could you reword it to something like "in that mode /api/scenes accepts every request that reaches Pascal, so make sure the app is only reachable through the proxy"? It's also worth one line saying PASCAL_AUTH=proxy is ignored when PASCAL_ADMIN_PASSWORD is set, since the password wins in resolveAuthMode.
2. Title and description. The PR is now a docs change, so please retitle it (e.g. docs: reverse-proxy setup for the scene API) and update the description so it matches what actually lands.

Happy to merge once those are in.

[chbndrhnns]

Thanks @Aymericr! Updated:

1. SETUP.md & .env.example:
   • Reworded PASCAL_AUTH=proxy to make it clear that in proxy mode /api/scenes accepts every request that reaches Pascal (so the app must be protected by the upstream proxy).
   • Added the note that PASCAL_AUTH=proxy is ignored when PASCAL_ADMIN_PASSWORD is set.
2. PR Metadata:
   • Retitled the PR to docs: reverse-proxy setup for the scene API.
   • Updated the description to reflect the documentation changes.
   • Rebased cleanly onto latest main.

[Aymericr]

Thanks @chbndrhnns, both of my points are in and the wording reads well now. One last thing before I merge: the rebase seems to have dropped two lines from the "Loopback stays open" bullet in SETUP.md. It now ends mid-sentence at "reached at", and the note about setting PASCAL_ADMIN_PASSWORD when you open a dev server to your LAN is gone. Could you restore those two lines as they are on main? Once that's back I'll merge.

[Aymericr]

This bullet now stops at "reached at". Please restore the two lines that were removed here:

  `localhost` need no password. Opening a dev server to another device on your LAN counts
  as a network host: set `PASCAL_ADMIN_PASSWORD` in `.env.local` for that.

[chbndrhnns]

Good catch! Restored those two lines to the "Loopback stays open" bullet in SETUP.md exactly as they are on main:

- **Loopback stays open.** `bun dev`, the CLI's managed editor and `docker run` reached at
  `localhost` need no password. Opening a dev server to another device on your LAN counts
  as a network host: set `PASCAL_ADMIN_PASSWORD` in `.env.local` for that.

Amended and force-pushed. Thank you for the review!

[Aymericr]

Thanks @chbndrhnns, the "Loopback stays open" lines are back exactly as on main, and everything from the earlier rounds is in. Docs look good to me. CI on forks needs a maintainer to approve the workflow run, so this will go in once that's done.