PAT-2167 Apps Proxy preview links (3/3): routing, session gate and docs

[pepamartinec]

Release Notes

https://linear.app/keboola/issue/PAT-2167
Depends on #2663

Part 3 of 3: wires preview links into apps-proxy. GET /_proxy/preview serves the landing page, the POST redeems the link into __Host-kbc-app-preview-session, and while the host is in dev mode that cookie skips the app's auth rules. The cookie is stripped from every request before anything reaches the app. Docs: docs/apps-proxy/preview-link.md.

The routing order is the part to review. /_proxy/* is routed before the preview session, so sign-out and the OIDC callback always reach apps-proxy, and sign-out clears the preview cookie. The kai-preview cookie check and iframe fallback moved below the preview session (otherwise the 303 → / after a redeem inside the kbc-ui iframe would get the kai shim). Side effects: a kai-preview cookie no longer forwards any /_proxy/* path to the app, an iframe load on a /_proxy/* path no longer gets the shim, and on apps without auth handlers /_proxy/preview no longer reaches the app.

Follow-up before sessions ever carry a user identity: close login CSRF. Any page can send a browser to someone else's link and the landing page submits it, so the browser gets that person's session. Harmless now (no identity), noted under Known limits. Candidate fix: auto-submit only when Sec-Fetch-Site is none or Sec-Fetch-Dest is iframe, otherwise show a button (same-site is not enough: other *.hub.* hosts are same-site).

Stack E2E on dev-keboola-gcp-us-central1 passed on abab227c (24 checks, 0 fail) with test limits 2m / 5m. Later changes (production limits, 5-min slide, review fixes) were not re-run on the stack.

• sandboxes-service: https://github.com/keboola/sandboxes-service/pull/730, https://github.com/keboola/sandboxes-service/pull/729, https://github.com/keboola/sandboxes-service/pull/728
• kbc-stacks testing config: https://github.com/keboola/kbc-stacks/pull/25478

Plans for customer communication

None.

Impact analysis

No impact until a stack sets APPS_PROXY_PREVIEW_JWKS_URL, apart from the kai-preview side effects above. APPS_PROXY_PREVIEW_ISSUER must be byte-equal to sandboxes-service's iss, or every link gets 401. The kbc-ui iframe needs the UI origin in APPS_PROXY_PREVIEW_ALLOWED_FRAME_ANCESTORS.

Change type

New feature

Justification

Let agents and the kbc-ui iframe open dev-mode apps through a short-lived signed link instead of the kai-preview handshake.

Deployment

Merge & automatic deploy, after parts 1 and 2. Before enabling on a stack: production signing keys and the APPS_PROXY_PREVIEW_* values.

Rollback plan

Revert of this PR, or unset APPS_PROXY_PREVIEW_JWKS_URL.

Post release support plan

None.

[linear-code]

PAT-2167

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[keboola-pr-reviewer-bot]

Verdict: needs_human (risk 4/5) · profile psgo

Needs human: new signed-link session gate on the apps-proxy request path that bypasses apps' configured AuthRules in dev mode.

Impact flags: possible rollback re-introduction — see Check Run summary.

Concerns:

• internal/pkg/service/appsproxy/proxy/apphandler/preview.go: New auth gate lets preview session skip app AuthRules in dev mode
• internal/pkg/service/appsproxy/proxy/apphandler/apphandler.go: Routing reorder changes evaluation of /_proxy, kai-preview, session, AuthRules
• docs/apps-proxy/preview-link.md: Author-noted login-CSRF limitation left as follow-up, not yet fixed

Suggested reviewers: @pr-author