/.well-known/workflow/v1/* routes blocked by proxy whitelist on self-hosted

[julianwitzel]

Description

The proxy whitelist in apps/web/proxy.ts redirects all unwhitelisted paths to /login on self-hosted deployments (when NEXT_PUBLIC_IS_CAP !== "true"). The .well-known/workflow/v1/* routes — used by @workflow/world-local for queue dispatch and step execution — aren't in the whitelist.

When start(transcribeVideoWorkflow, ...) (or any other workflow start() call) tries to POST to /.well-known/workflow/v1/flow, it gets a 307 → /login instead of the expected workflow response. The dispatch fails silently, the workflow never executes, and any feature relying on workflows (transcription, AI summaries) stalls.

Reproduction

1. Self-host Cap with NEXT_PUBLIC_IS_CAP unset
2. From inside the cap-web container:

   wget -qO- http://127.0.0.1:3000/.well-known/workflow/v1/step

Returns the login page HTML instead of a workflow response.
3. Or trigger a transcription: it stalls at transcriptionStatus = "PROCESSING" indefinitely, no /audio/extract calls reach the media-server.

Root cause

In apps/web/proxy.ts lines ~40-56:

if (buildEnv.NEXT_PUBLIC_IS_CAP !== "true") {
  if (
    !(
      path.startsWith("/s/") ||
      path.startsWith("/middleware") ||
      path.startsWith("/dashboard") ||
      path.startsWith("/onboarding") ||
      path.startsWith("/api") ||
      path.startsWith("/login") ||
      path.startsWith("/signup") ||
      path.startsWith("/invite") ||
      path.startsWith("/self-hosting") ||
      path.startsWith("/terms") ||
      path.startsWith("/verify-otp")
      // /.well-known/ missing — blocks workflow internal routes
      // /embed/ also missing — see #906 / PR #1415
    ) &&
    process.env.NODE_ENV !== "development"
  )
    return NextResponse.redirect(new URL("/login", url.origin));

Fix

Same shape as #906:

       path.startsWith("/verify-otp") ||
+      path.startsWith("/embed/") ||
+      path.startsWith("/.well-known/")

The /.well-known/ path is reserved by RFC 8615 for well-known URIs and is a sensible whitelist entry generally — workflow routes, ATproto verification, etc. all live under it.

Verified

After applying both whitelist additions plus the workflow-race fix from #1550, the full transcription + AI pipeline runs end-to-end on self-hosted (Hetzner CPX41, cap-web built from current main).

Environment

• Cap version: built from main commit 52b0acc
• Self-hosted via Docker compose (Hetzner)
• Other services in stack: Hetzner S3, MySQL 8, cap-media-server (latest)

[linear]

CAP-700

[tembo]

This is a well-documented issue. The fix at apps/web/proxy.ts lines 40-56 is straightforward - the whitelist just needs /.well-known/ added.

Related work:

• Issue /embed/* routes redirect to /login on self-hosted, breaking iframe embeds #1768 reports the exact same problem for /embed/* routes, filed just two days ago
• PR #906 Fix video embedding. #1415 attempted to fix Self-hosted Cap Web doesn't support embeds #906 (embed issue) but hasn't been merged yet
• PR fix self-hosted transcribtion and thumpnail unavailable #1746 addresses related self-hosted transcription issues and upgrades the workflow package to 4.2.4, which may be needed alongside this fix if you're hitting the ArrayBuffer bug from Transcription workflow fails on Docker image with Node 24 #1550

Implementation note: The workflow routes are served from apps/web/public/.well-known/workflow/v1/ and configured in both apps/web/next.config.mjs (line 23) and apps/web/vercel.json (line 4). The @workflow/world-local package uses these endpoints for queue dispatch and step execution.

Suggested combined fix covering both this issue and #1768:

path.startsWith("/verify-otp") ||
+ path.startsWith("/embed/") ||
+ path.startsWith("/.well-known/")

Using /.well-known/ (without trailing wildcard) is correct since startsWith handles the prefix matching - this also future-proofs for other well-known URIs like the existing atproto-did verification endpoint.