Security Model

Overview

This document defines security behavior for remote compute routing and worker APIs.

Scope lanes

Public lane scopes

Used by application/admin clients:

• trigger:write
• runs:read
• runs:write
• deploy:read
• deploy:write

Internal world-proxy lane

Used for internal calls forwarded by workflow-studio/world-remote:

• world:proxy

This lane is required for world-proxy routes.

Admin scope

admin grants full access.

API key handling

• API keys are stored as hashes.
• Scope checks are applied per route.
• Keys can be revoked.

Use separate keys for public lane traffic and internal world-proxy traffic in production.

Production reroute guard

Strict guard applies when:

• NODE_ENV=production.

In strict mode, remote startup requires:

• WORKFLOW_TARGET_WORLD to be present,
• and to match expected target (workflow-studio/world-remote).

App-host compute guard

When remote reroute is active, app-host queue handlers return HTTP 409 to prevent local compute execution drift.

This behavior is intentional and used by ownership diagnostics.

Ownership detection

The ownership detector identifies queue callback requests that reach the application host instead of the remote worker. These are "unexpected hits" — evidence of misconfigured routing.

Match criteria

A request is classified as a queue callback when all of these conditions are met:

1. Method: POST
2. Path: /.well-known/workflow/v1/flow or /.well-known/workflow/v1/step
3. Content-Type: contains application/json or +json
4. Marker header: at least one of:
   • x-vqs-signature
   • x-vqs-delivery-id
   • x-workflow-queue-provider
   • x-workflow-message-id

If any condition fails, the request is not classified as a queue callback and is ignored by the detector.

Body shape check

The detector also checks whether the request body contains runId or workflowRunId (string fields). This result is reported in lastEvent.bodyShapeMatched but is not gating — a request matching the four criteria above is recorded as an unexpected hit regardless of body shape.

Status model

The diagnostics endpoint returns an ownership status field:

Counters:

• lifetimeUnexpectedHits — total since process start.
• unexpectedHitsLast15m — count in the rolling 15-minute window.
• lastUnexpectedHitAt — ISO timestamp of the most recent unexpected hit.

See workflow-studio diagnostics for the full response shape and authentication details.

Operational checklist

• Set WORKFLOW_TARGET_WORLD=workflow-studio/world-remote on application deployment.
• Keep WORKFLOW_COMPUTE_API_KEY server-only.
• Use validate-ownership --strict before production rollout.
• Monitor audit logs for lane and scope anomalies.