feat(workflow-executor): validate bearer claims via a zod middleware [PRD-508]

[Scra3]

What

Validates the bearer JWT payload as early as possible via a zod middleware, instead of the ad-hoc Number.isFinite check in handleTrigger. Follow-up to PRD-477.

koa-jwt only validates a token's signature + expiry — never the payload shape. So ctx.state.user.id was not guaranteed; hasRunAccessMiddleware even did as StepUser without validating (latent gap).

Changes

• src/http/bearer-claims.ts — BearerClaimsSchema = z.object({ id: z.number() }). Non-strict on purpose: jsonwebtoken adds iat/exp to the decoded payload and Forest may send extra claims — a strict schema would reject every real token. Only id is consumed downstream (handleTrigger + hasRunAccess → ?userId=); StepUserSchema (9 required fields) is a different contract and isn't reusable.
• Middleware right after koa-jwt — validates ctx.state.user once; on failure throws UnauthorizedHttpError. Both routes now receive a user with a guaranteed numeric id.
• handleTrigger — drops the Number.isFinite branch.

⚠️ Behaviour change

A well-signed token without a valid numeric id now returns 401 Unauthorized (invalid credentials, consistent with koa-jwt's own 401s) instead of 400.

Out of scope (decided)

pendingData is not boundary-validatable — its schema is step-type-dependent (patchBodySchemas[execution.type]), known only after getAvailableRun. It stays validated downstream in base-step-executor. A boundary z.union/z.discriminatedUnion was considered and rejected (accepts the wrong step type; .transform() footgun; no discriminator in the front-sent payload).

Tests

• test/http/bearer-claims.test.ts: accepts { id } and { id, iat, exp, … } (the non-strict trap), rejects missing/non-numeric id.
• test/http/executor-http-server.test.ts: invalid claims → 401; a token with extra claims → 200 (end-to-end non-strict proof).
• Full suite: 1025 passing.

Note

Stacked on feature/prd-477-… (base of this PR) — it builds on the typed HTTP errors / middleware from PRD-477. Retarget to main once PRD-477 merges.

fixes PRD-508

Note

Validate bearer JWT claims via Zod middleware in workflow-executor HTTP server

• Adds a Zod-based middleware in executor-http-server.ts that validates ctx.state.user against BearerClaimsSchema (integer id required); invalid payloads receive 401 before reaching any route handler.
• Introduces http-errors.ts with typed HTTP error classes and a toHttpError utility that maps domain error categories to HTTP statuses: 404 for NotFoundError, 403 for AccessDeniedError, 503 for UnavailableError, 400 for uncategorized WorkflowExecutorError, and 401 for koa-jwt errors.
• Refactors domain errors in errors.ts into abstract category base classes (NotFoundError, AccessDeniedError, UnavailableError) so HTTP translation is driven by error category rather than per-handler branching.
• Removes manual user-id extraction and per-error branching from route handlers; all error responses are now handled by a centralized error-translation middleware.
• UserMismatchError now requires both bearerUserId and ownerUserId in its constructor, including both in the technical log message while keeping a generic user-facing message.

^{Macroscope summarized bde84af.}

[linear-code]

PRD-508

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/http/executor-http-server.ts	100.0%
	packages/workflow-executor/src/http/bearer-claims.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[qltysh]

All good ✅

[matthv]

LGTM