SIGN IN SIGN UP

[docs] Document Postgres World auth/security limitations explicitly (#3908)

* [docs] Document Postgres World auth/security limitations explicitly

The Postgres World was described as "production-ready" in the docs, the
worlds manifest, and the building-a-world guide, while its README mentioned
"reference implementation" only in passing and neither said anything about
authentication. It inherits its queue HTTP handler from world-local, which
validates the x-vqs-* header shape, the queue-name prefix, and the payload
schema — never the caller — so any client that can reach
POST /.well-known/workflow/v1/flow can forge or replay workflow and step
invocations.

Make the reference-implementation framing and the bring-your-own-auth
expectation explicit instead:

- Add a Security section to the package README, HOW_IT_WORKS, and both the
  v4 and v5 Postgres World docs pages: what is unauthenticated, how to gate
  it at the network edge, why framework middleware is the wrong layer, and
  that the World never presents a credential of its own.
- Note that the World does not implement getEncryptionKeyForRun(), so data
  is stored unencrypted, and that self-hosted @workflow/web has no auth.
- Drop "production-ready" from the docs pages, the worlds manifest, and the
  building-a-world reference callout, and add "no built-in authentication"
  and "no encryption" to the Limitations list.
- Stop the Local World pages from pointing at the Postgres World for
  production without mentioning that it shares the same unauthenticated
  handler, and warn about self-hosted World security in the Deploying guide
  and the v5 Worlds configuration reference.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>

* [docs] Address review feedback on Postgres World security docs

- Revert the additions to deploying.mdx (v4 + v5) and the v5 Worlds
  configuration reference: those pages stay a short link section and general
  configuration, with the security detail living on the Postgres World pages.
- Apply the suggested wording for building-a-world, local.mdx, the Postgres
  frontmatter description, the Security intro (now also recommending
  encryption), the "does not currently implement" limitation, and the worlds
  manifest description.
- Condense "What is unauthenticated" into "Protect the queue route": the flow
  route is publicly reachable by default and must be protected, plus the two
  exceptions (webhook token, manifest 404).
- README: add the clone-and-adapt recommendation to the notice, note that a
  derived World can opt into encryption by implementing
  getEncryptionKeyForRun(), and drop the redundant Queue Behavior bullet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>

* [docs] Restore the closing Callout tag in the v5 building-a-world callout

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* [docs] Link the Next.js setup guide without the accordion fragment

The `configure-proxy-handler` id lives on a JSX heading inside a collapsed
accordion, so next-validate-link cannot see it and the anchor would not reveal
the content anyway.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* [docs] Scope the Postgres World ingress guidance to the flow route

Blocking all of `/.well-known/workflow/` breaks `createWebhook()`, whose
`webhook/:token` route is a sibling under the same prefix and is meant to be
reachable by the caller. Also note that WORKFLOW_PUBLIC_MANIFEST is read at
build time, and attribute payload validation to the runtime rather than the
queue handler, which only checks the header shape and queue-name prefix.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Co-authored-by: Peter Wielander <peter.wielander@vercel.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
P
Pranay Prakash committed
5093edebbb39e6c5249da18b3d6687c807d19d80
Parent: 413c6c9
Committed by GitHub <noreply@github.com> on 9/23/2026, 5:20:28 PM