Flow route queue auth, stage 3: a signing mode for Worlds on external push-based queues

Open
#5,427 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
15/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
typescript

Research direction

This is design work, so start by reading the QueueAuthMode type and its TODO in packages/world/src/queue.ts, then authorizeQueueDelivery() in packages/core/src/runtime/queue-auth.ts, and how keys are registered in @workflow/utils. The issue asks for a signed-delivery mode with key rotation and conformance tests in @workflow/world-testing, but the design is still a sketch. Done means an agreed design, then a mode whose refusals return 401 with the refused marker, never write to a run, and pass the gated conformance tests.

Written by the indexing model from the issue text.

Description

Summary

Queue.queueAuthMode (@workflow/world) tells the runtime how to authenticate a delivery that reaches the flow route (POST /.well-known/workflow/v1/flow). After #5179 and #5315 the modes are:

  • 'deny': a pull-based World. The World's worker runs inside the app's process and delivers to the route's in-process entry; the route refuses every HTTP request with a final 403. The Postgres World declares it.
  • 'allow': the route accepts HTTP because the platform already restricts who can reach it. The Vercel World declares it: only Vercel Queues can trigger the route, and the handler receives a message ID and leases the message through Vercel Queues. (Named 'skip' in @workflow/world 5.2.0; 'skip' is still accepted as a deprecated spelling.)
  • 'loopback': the Local World's shared queue key, a temporary mode until the Local World no longer delivers back to the app over its own routes.

None of these fits a World backed by an external push-based queue, such as Amazon SQS or Cloudflare Queues, that delivers to the flow route over HTTP from outside the app's platform: 'allow' leaves the route open to anyone who can reach it, and 'deny' cannot receive the delivery at all.

Stage 3: a signing mode

Add a mode in which the World signs each delivery and the runtime verifies the signature before it reads the body or touches any run.

Sketch, to be refined when the work starts:

  • The World holds the signing key and attaches a signature header to each delivery, over the body, the message ID, the attempt and a timestamp, so a captured delivery cannot be replayed later or against another message.
  • The runtime verifies with a key the World provides through the existing key-source registration in @workflow/utils, refuses a bad or stale signature with a 401 that carries the existing refused marker (so a sender can rotate keys and retry), and never writes to a run on a refusal.
  • Key rotation: accept the current and the previous key for a bounded window.
  • WORKFLOW_QUEUE_AUTH=off keeps its meaning (an emergency override, refused while dynamic workflows are enabled).
  • Conformance coverage in @workflow/world-testing, gated on the declared mode like the existing skipUnlessKeyChecked and skipUnlessDenied helpers.

The extension point is QueueAuthMode in packages/world/src/queue.ts and authorizeQueueDelivery() in packages/core/src/runtime/queue-auth.ts; a TODO next to the type points here.

Out of scope

Changing how 'deny' or 'allow' Worlds are checked, and the Local World's 'loopback' mode.

Dominant language
TypeScript
Stars
2.5k
Forks
401
Avg merge
1d 21h
Merged PRs (30d)
201

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from vercel/workflow

All issues in vercel/workflow

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.