docs(workflow-executor): document FOREST_EXECUTOR_ENCRYPTION_KEY

[hercemer42]

What

Documents FOREST_EXECUTOR_ENCRYPTION_KEY in the workflow-executor README — a new "OAuth-protected MCP connectors" section covering:

• what it encrypts (the OAuth credentials the executor stores, AES-256-GCM at rest)
• how to generate it (openssl rand -hex 32) and to keep it separate from FOREST_AUTH_SECRET
• using the same value across instances that share a database
• its lazy behaviour (while unset, credential storage returns 503 and those connectors stay unavailable; the executor still boots, with a startup warning)
• no managed rotation — changing it forces affected users to reconnect

It complements the one-line entry already in .env.example.

Why

PRD-626 (the docs half of PRD-367): operators deploying the executor with OAuth-protected MCP connectors need a README reference for this variable.

Base / merge order

Based on the PRD-692 branch (feature/prd-692-harden-executor-oauth-runtime-clear-idempotency-phase-on, #1724) — the top of the OAuth-MCP executor stack, where FOREST_EXECUTOR_ENCRYPTION_KEY and the code that reads it already live. Targeting that branch keeps this diff to just the README change. Intended to merge last, once PR1 (#1619), PR2 (#1665) and PRD-692 (#1724) are in.

Replaces docs-site PR ForestAdmin/docs#3 (now closed) — the executor's own README, next to the code and .env.example, is the right home for an operator-facing deployment variable (and "executor" isn't a concept on the public docs site).

Refs: PRD-626

🤖 Generated with Claude Code

Note

Document FOREST_EXECUTOR_ENCRYPTION_KEY in workflow-executor README

Adds an 'OAuth-protected MCP connectors' section to README.md explaining how the executor encrypts per-user OAuth credentials at rest using FOREST_EXECUTOR_ENCRYPTION_KEY. Covers key generation, the requirement to use a separate secret from FOREST_AUTH_SECRET, that the key is only needed when OAuth-protected connectors are in use, and that all instances sharing a database must use the same key.

^{Macroscope summarized 1087b4a.}

[linear-code]

PRD-367

PRD-626

[qltysh]

Coverage Impact

This PR will not change total coverage.

🚦 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.

[Scra3]

Docs review (PRD-367 PR4). The section is accurate against the implementation; one small suggestion.

[Scra3]

suggestion: unlike FOREST_ENV_SECRET, the key's length/format is not validated by the code — worth noting operators must use the exact openssl rand -hex 32 output, since a weak value is accepted silently.

[hercemer42]

Good catch — confirmed against the code: deriveKey() only throws on an empty value and otherwise feeds the secret straight into hkdfSync, so length/format aren't validated and a weak value is accepted silently.

Added a note to the entry: "The value isn't validated, so use a genuinely random secret."

I framed it around entropy rather than the exact openssl rand -hex 32 output, since the code accepts any non-empty secret (HKDF), not only hex — so the real requirement is a high-entropy value. Thanks for the review!

[qltysh]

All good ✅

[macroscopeapp]

🟡 Medium src/mcp-auth-error.ts:42

isMcpAuthError returns true for an error whose message matches /unauthorized/i even when a later link in the cause chain carries an explicit 403 status. For example, new Error('Unauthorized scope', { cause: Object.assign(new Error('forbidden'), { status: 403 }) }) is classified as refreshable auth, because .some() returns at the outer message match before the inner 403 is inspected. The comment states an explicit status is authoritative, but the implementation lets a message match short-circuit before any later status is checked. Consider scanning the full chain for an explicit non-refreshable status before falling back to message matching.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/ai-proxy/src/mcp-auth-error.ts around line 42:

`isMcpAuthError` returns `true` for an error whose message matches `/unauthorized/i` even when a later link in the cause chain carries an explicit `403` status. For example, `new Error('Unauthorized scope', { cause: Object.assign(new Error('forbidden'), { status: 403 }) })` is classified as refreshable auth, because `.some()` returns at the outer message match before the inner `403` is inspected. The comment states an explicit status is authoritative, but the implementation lets a message match short-circuit before any later status is checked. Consider scanning the full chain for an explicit non-refreshable status before falling back to message matching.

[macroscopeapp]

🟡 Medium

agent-nodejs/packages/workflow-executor/src/build-workflow-executor.ts

Line 198 in e3db719

async start() {

createWorkflowExecutor.start() calls runner.start() before server.start(), so the polling loop can invoke DatabaseMcpOAuthCredentialsStore.get() — which issues SELECT against ai_mcp_oauth_credentials — before ExecutorHttpServer.start() runs mcpOAuthCredentialsStore.init() to create the table. On startup with a pending OAuth-backed step, the first poll cycle fails with a missing-table error instead of executing the run. Consider awaiting the store migration before runner.start(), or calling init() explicitly in buildDatabaseExecutor prior to starting the runner.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/workflow-executor/src/build-workflow-executor.ts around line 198:

`createWorkflowExecutor.start()` calls `runner.start()` before `server.start()`, so the polling loop can invoke `DatabaseMcpOAuthCredentialsStore.get()` — which issues `SELECT` against `ai_mcp_oauth_credentials` — before `ExecutorHttpServer.start()` runs `mcpOAuthCredentialsStore.init()` to create the table. On startup with a pending OAuth-backed step, the first poll cycle fails with a missing-table error instead of executing the run. Consider awaiting the store migration before `runner.start()`, or calling `init()` explicitly in `buildDatabaseExecutor` prior to starting the runner.