fix(security): stop a project's CSRF policy blocking its own release asset build

[kojiwakayama]

The failure

A customer demo project set

security: { csrf: { excludePaths: ["/api/ag-ui"] } }

to keep CSRF enforced everywhere except the agent endpoint its chat client
posts to. Deploy then failed with

Release assets were not ready within 120s (last state: missing)

The developer compared manifests across releases — four consecutive releases
carrying a nested csrf object have no manifest, releases before and after
report state=ready — and shipped csrf: false on a sign-in-protected
customer demo because it was the only setting that deployed.

Mechanism

The manifest is built by the project runtime, not the CLI. The control plane
POSTs a signed operation envelope to
/api/control-plane/runs/{runId}/execute with
target: "task:release-asset-build"; that dispatch is the only caller of
beginReleaseAssetManifestBuild (src/release-assets/build-executor.ts:2297).
Until it lands, no manifest row exists and the state reads missing.

CsrfHandler (src/security/http/csrf/csrf-handler.ts:63) registers at
priority 5 with patterns: [], so it runs in front of
ProjectRunExecuteHandler for that POST
(src/server/runtime-handler/index.ts:138-159,
src/routing/registry/registry.ts:86-101). The control plane is not a browser:
it carries no __Host-vf_csrf cookie and authorizes from the JWS the handler
verifies. So the gate answered the project's own build dispatch with
403 Forbidden – invalid or missing CSRF token, the run failed before the
manifest existed, and the deploy surfaced 120 seconds later naming neither
CSRF nor config.

The boundary is not the nested object. csrf: true fails identically —
only an absent or false setting ever built a manifest. Absent is the common
case because the task rail dispatches to the main-branch runtime, which
resolves as preview, so the production csrf default never applies there
(src/security/http/config.ts:271). That is why manifests build for everyone
who never wrote the key.

Fix

isControlPlaneSurfaceRequest (src/channels/control-plane.ts) exempts the
signed control-plane prefix from the CSRF gate — the same shape as the existing
isCspReportRequest exemption, and for the same reason: the gate expects a
browser credential the caller cannot hold. Every handler behind that prefix
authenticates its envelope through verifyControlPlaneRequest before acting
(runs execute/resume/cancel/stream, agents list), so the exemption removes no
authorization. The prefix is matched against URL.pathname, which resolves dot
segments, and a path that merely starts alike
(/api/control-plane-mirror/...) stays gated.

Tests

src/release-assets/build-dispatch-security.test.ts drives the real chain —
CsrfHandler then ProjectRunExecuteHandler, with a real signed envelope —
across all four csrf shapes and asserts the release asset build executor is
reached.

Red, before the fix:

release assets: control-plane build dispatch ... builds a manifest when the project enables csrf with a boolean
error: AssertionError: Values are not equal: release asset build never started; runtime answered 403: Forbidden – invalid or missing CSRF token
-   false
+   true

release assets: control-plane build dispatch ... builds a manifest when the project excludes a path from csrf
error: AssertionError: Values are not equal: release asset build never started; runtime answered 403: Forbidden – invalid or missing CSRF token
-   false
+   true

FAILED | 0 passed (2 steps) | 1 failed (2 steps)

Green, after:

release assets: control-plane build dispatch ...
  builds a manifest when the project leaves csrf unset ... ok
  builds a manifest when the project disables csrf ... ok
  builds a manifest when the project enables csrf with a boolean ... ok
  builds a manifest when the project excludes a path from csrf ... ok
ok | 1 passed (4 steps) | 0 failed

Plus two cases in csrf-handler.test.ts: a run dispatch passes for every
enabled csrf shape, and a look-alike prefix is still rejected. No existing test
was changed or weakened.

Not fixed here, worth a follow-up

• AuthHandler has the same hole. It runs at priority 0, exempts only
  isCspReportRequest, and reads security.auth
  (src/security/http/auth.ts:156-183). A project that configures basic or
  bearer auth in veryfront.config.ts should be expected to 401 its own
  control-plane dispatches the same way. Not changed here because it needs its
  own reproduction rather than a symmetric guess.
• Legibility. This fix removes one instance; the shape stays. A config
  value can still stop a manifest with the failure surfacing 120 s later as a
  timeout that names no cause. What would close that: have deploy read the
  release-asset build run's terminal state and error alongside the manifest
  state, so last state: missing can say why the build never began.

Summary by CodeRabbit

• Bug Fixes

  • Improved reliability for signed control-plane operations by allowing valid requests to proceed without requiring a CSRF token.
  • Restricted this exception to recognized paths, supported methods, and valid signatures, preserving protection for look-alike or unrelated requests.
  • Ensured release-asset build dispatch works consistently across different CSRF configuration settings.

• Tests

  • Added coverage for successful dispatch, supported request variations, and rejection of invalid paths, methods, and signatures.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 658a17d4-3c9d-4dce-9926-ee76d11c9e5f

📥 Commits

Reviewing files that changed from the base of the PR and between 6c9efa1 and 6b5c5de.

📒 Files selected for processing (1)

• src/channels/control-plane.ts

---

📝 Walkthrough

Walkthrough

The change adds shared control-plane route classification and signed dispatch detection. The CSRF handler bypasses validation for registered signed dispatches. Tests cover route rejection and release-asset manifest execution across CSRF configurations.

Changes

Control-plane CSRF dispatch

Layer / File(s)	Summary
Define shared control-plane route classification src/channels/control-plane.ts, src/proxy/control-plane-signature.ts	Adds method-specific route matching and signed dispatch detection. The proxy uses the shared route predicate.
Bypass CSRF for signed dispatch src/security/http/csrf/csrf-handler.ts, src/security/http/csrf/csrf-handler.test.ts, docs/api-reference/veryfront/security.md	The CSRF handler bypasses validation for signed registered control-plane requests. Tests cover supported routes, missing signatures, unsupported methods, and look-alike paths.
Validate release-asset dispatch src/release-assets/build-dispatch-security.test.ts	Runs signed control-plane requests through the CSRF and project-run handlers. Tests cover unset, disabled, enabled, and excluded-path CSRF configurations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• veryfront/veryfront-code#3357: Both changes update control-plane route classification in src/proxy/control-plane-signature.ts.

Suggested reviewers: kwakayama, ariskemper

Sequence Diagram(s)

sequenceDiagram
  participant ControlPlaneRequest
  participant CsrfHandler
  participant ProjectRunExecuteHandler
  participant ManifestBuilder
  ControlPlaneRequest->>CsrfHandler: Submit signed execution request
  CsrfHandler->>ProjectRunExecuteHandler: Continue without CSRF token validation
  ProjectRunExecuteHandler->>ManifestBuilder: Begin manifest building

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main security fix: preventing project CSRF policy from blocking its own release asset build.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/csrf-blocks-release-asset-build

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e055307f43

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".