feat(agent): serve a BFF in-process with addBff()

[nbouliol]

Stacked on #1875. This is where the stack becomes a feature.

Why

Running a BFF meant a second deployment: another process, another port, another set of secrets to keep in sync with the agent's — for a component whose only job is to sit in front of that same agent.

What

createAgent(options)
  .addDataSource(/* … */)
  .addBff({ allowedOrigins: ['https://my-app.com'] })
  .start();

Served at /bff on the agent's own port, on every mount target. The BFF reaches the agent through the in-process dispatcher the embedded MCP server already uses: no socket, no agent url to guess per host framework, no second listener.

authSecret, envSecret, forestServerUrl, forestAppUrl and the logger are inherited — a divergent authSecret would make the agent reject the very tokens the BFF mints, as an opaque 401. What is left are features the BFF switches on: tokenEncryptionKey (the OAuth login/refresh flow, and with it the AI relay — it gates that flow, not the data surface, which answers to any bff_access bearer signed with authSecret), allowedOrigins (browser access), openapiEnabled (the docs, off by default when embedded because the document is not filtered per caller).

Three lifecycle details that are easy to get wrong, and are tested:

• The dispatcher is registered in addBff(), not at start(). getInProcessDispatcher() pushes its hook the first time it is called, and mount() only runs the hooks registered before it — asked for later, every BFF call would throw not mounted yet until the first restart.
• /bff answers 503 while the agent is starting, rather than falling through to the host's 404, which would read as "wrong url" instead of "not started".
• stop() stops answering. The host application keeps whatever middleware it registered, so without it a stopped agent would keep serving BFF data through a dispatcher pointing at a dead stack.

restart() invalidates what the BFF read from the SaaS — a restart means the customizations changed.

addBff() refuses a second call, and refuses to coexist with an MCP server mounted under /bff in either order — including the spellings bff, /bff/ and /bff/ai, which the MCP server normalizes onto the same prefix. The BFF is registered at builder time and wins the root middleware's first-match, so the MCP surface would boot, log success and never be reachable.

The build cycle

agent gains an optional peer dependency (exact pin, like every internal dep — multi-semantic-release rewrites those ranges on release) plus a dev dependency on @forestadmin/agent-bff, which would close the cycle agent → agent-bff → agent-testing → agent that lerna run build sorts on. It is broken by moving the search integration suite out of agent-bff, which loses its dev dependency on the agent.

engines: { node: ">=22.12.0" } is declared on the agent too: addBff() pulls in a package that requires it, and the agent declared nothing.

Tests

agent-bff 82 suites / 1368 tests, agent 87 suites / 1587 tests.

The moved suite becomes test/bff/embedded-bff.e2e.test.ts: a real Agent over a real datasource, mounted on Express, with a real BFF in front — list, search, relation-extended search, count, and an agent-side refusal surfacing as the BFF error contract. It also pins what the unit tests cannot see: /forest still answers next to it, /bffalo is not claimed, and a stopped agent answers 503. Its data contract runs twice — over the in-process dispatcher, and over a real socket against a listening agent, so the HTTP transport the standalone deployment uses keeps a gate. The CI job that ran the old suite now runs this one, and the unit job ignores it.

Fixes PRD-1076

🤖 Generated with Claude Code

Note

Add in-process BFF support to Agent via addBff()

• Adds Agent.addBff() to configure an in-process embedded BFF, dynamically loading the optional @forestadmin/agent-bff package.
• Introduces the EmbeddedBff class to handle BFF build, lifecycle, and request routing under /bff.
• Updates resolveTransport to prefer an in-process dispatcher over HTTP when available.
• Hardens CORS middleware to reject disallowed cross-origin requests with a 403 error before downstream handling.
• Updates /health to report explicit configured flags for oauth, ai, cors, and openapi.
• Risk: Agent.mountAiMcpServer() and addBff() throw if MCP paths overlap /bff; parseConfig hasAllRequired no longer requires BFF_TOKEN_ENCRYPTION_KEY.

^{Macroscope summarized e05ddeb.}

[linear-code]

PRD-1076

[qltysh]

2 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): buildAgentRouteMiddlewares	2

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (11)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/http/health-route.ts	100.0%
	packages/agent/src/agent.ts	100.0%
	packages/agent-bff/src/cors/cors-middleware.ts	91.7%	29
	packages/agent-bff/src/agent/in-process-transport.ts	100.0%
	packages/agent-bff/src/build-bff.ts	100.0%
	packages/agent-bff/src/config/env-config.ts	100.0%
	packages/agent-bff/src/http/bff-http-server.ts	100.0%
	packages/agent-bff/src/index.ts	100.0%
	packages/agent/src/framework-mounter.ts	100.0%
	packages/agent/src/embedded-bff.ts	98.1%	24
	packages/agent/src/bff-routes.ts	100.0%
	Total	98.5%

🤖 Increase coverage with AI coding...

In the `feature/prd-1076-7-add-bff` branch, add test coverage for this new code:

- `packages/agent-bff/src/cors/cors-middleware.ts` -- Line 29
- `packages/agent/src/embedded-bff.ts` -- Line 24

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

[Tonours]

Spec (PRD-1076): steps 8, 9 (its /bff half), 10, 11, 12, 15 and 16 are all delivered, and the two packaging decisions the ticket asked for by name — engines: { node: ">=22.12.0" } and the exact-pinned optional peer — match step 15 word for word, so neither is in question here. Two steps landed partially:

• Step 13 asked that a buildBff failure not leave a half-started agent, "the host is already serving /forest when start() rejects, and a retry could duplicate hooks and subscriptions". The mounted flag and the audit-trail close are in, well reasoned. The retry half is not: subscribeToServerEvents() and onRefreshCustomizations() run before the failure point and there is no guard against a second start().
• Step 17 asked to "document that the Promise.race cancels nothing: an action cut at 10s keeps running agent-side, and a retry can double the mutation". The propagation itself is complete and I traced it end to end — agentTimeoutMs → config → resolveTransport → InProcessRequester → injectWithTimeout. The documentation is absent: git grep -i 'cancels nothing|keeps running|double the mutation' over both this PR and the docs PR returns nothing. It is a safety caveat about a doubled mutation, and embedded mode is what makes it reachable.

What I checked and found sound, so it does not get re-litigated: the bff-routes.ts helpers are correct on every input I threw at them, including /bff and /bff/ both stripping to / and never to '', /bffalo falling through, and query/fragment handling; the agent's auth chain genuinely still runs on the in-process path (the dispatcher injects into the mounted /forest router whose first root route installs jwt({ secret: authSecret }), and types.ts states the shared-secret invariant explicitly); getInProcessDispatcher() at builder time really is necessary and the comment explaining why is right; stop() leaks nothing, since agent-bff/src holds no timer; and the dependency direction between the two packages is now cleanly one-way.

One packaging mechanic worth a decision rather than a fix: engines: ">=22.12.0" is blocking under yarn 1 — an install failure, not a warning — and it ships here as a feat, so a minor bump. Any consumer still on Node 20 fails to install on a minor. The ticket asked for the field; it did not weigh that. Your call whether it wants a release note.

Eleven findings inline, three of them Must fix.

[nbouliol]

Pushed 271c47b. Eleven inline findings answered individually — nine fixed, two partly, and the reasoning is in each thread. On the two points in the review body itself:

Step 13, the retry half. Addressed for the BFF: parseConfig now runs in EmbeddedBff.prepare(), called at the top of start() before buildRouterAndSendSchema(), subscribeToServerEvents() and mount(). The likeliest failure — a mistyped option — therefore happens before either the subscription or the restart listener exists, so a retry cannot duplicate them. The general "no guard against a second start()" is pre-existing Agent.start() behaviour on every failure path in the class, unrelated to addBff(), so I did not widen this PR into it.

Step 17, the Promise.race caveat. Documented on agentTimeoutMs in types.ts: it bounds how long the BFF waits and cancels nothing, an action cut at the deadline keeps running agent-side and still commits, so a client retrying on a timeout can double the mutation.

engines: ">=22.12.0" under yarn 1. Correct that it is a hard install failure, not a warning, and that it ships as a minor. Keeping the field — step 15 asked for it by name and addBff() pulls in a package that requires it — and I will add the release note, since a Node 20 consumer failing to install on a minor deserves a heads-up rather than a surprise.

Both suites green: agent-bff 82 suites / 1368 tests, agent 87 suites / 1587 tests, lint clean on both.

[Tonours]

All fourteen findings verified on 271c47b: collidesWithBff() normalizes the way mcp-server does, so 'bff', '/bff/' and '/bff/ai' all throw, and the comment has the direction right; the tokenEncryptionKey doc no longer claims an access control it does not provide; the unit job ignores embedded-bff.e2e; the load failure keeps its cause; prepare() validates before mount and before the SSE subscription; counters reach the host logs while gauges stay dropped; the e2e runs its data contract over both transports, HTTP included; bff_stopped is told apart from bff_not_started; originalUrl is claimed before the rewrite; the five test gaps and the barrel export are closed. Keeping the handler mounted on stop and keeping features on /health are both argued positions I accept.

One note, not blocking: the build workflow has not run on this head — only Macroscope and qlty report. Worth a re-run before merge.

[Tonours]

Delta since my last review (271c47b → 1e3ce47): rebase plus five commits — 5c8313d, a2c694d, 55875e0, ca5550f, 1e3ce47. One must-fix; the rest of the delta verified good (details at the end).

Must fix

The origin deny breaks same-origin mutating browser calls. createCorsMiddleware is installed unconditionally (build-bff.ts:526) and now refuses every request whose Origin is not in the allow-list (cors-middleware.ts:55-60, from 55875e0). Browsers send Origin on every same-origin POST/PUT/PATCH/DELETE, so a deployment whose own origin is not listed — the default, allowedOrigins starts empty — answers 403 origin_not_allowed to every list/count/action call from a same-origin UI. On main the same request was served (omit-header + log, #1868), and the README promises that contract: "Empty ⇒ no cross-origin browser access" (agent-bff/README.md:97) — same-origin implied working. This is also macroscopeapp's open thread on cors-middleware.ts:55; no test covers empty-list + Origin today.

Fix either way:

• treat a same-origin Origin as allowed (origin === ctx.origin, or Host comparison), or
• make the new contract explicit: the deployment's own origin must be listed, with a test for empty-list + same-origin POST and the README sentence rewritten.

Verified good in this delta

• 5c8313d (drop engines from the agent): right call — engines is a hard install failure under yarn 1 and this ships as a minor; the requirement stays on agent-bff, which is the optional peer.
• ca5550f (whitelist startup warning): both branches tested; never fails boot; names what still protects the route.
• 55875e0 health rename features → configured: honest naming, tests updated. Note the README in #1877 still documents the old key — flagged there.
• a2c694d / 1e3ce47: rename reconciliation and log prefixing, no behavior change.
• Rebase drift on the three rewritten commits is upstream absorption (mountPath, RootHandler, IN_PROCESS_AGENT_URL), nothing new snuck in.

CI: only LLM Integration Tests (ai-proxy) fails, on all seven PRs of the stack alike — an Anthropic-side thinking.type.disabled 400 on claude-fable-5-1, unrelated to this code.

[nbouliol]

Pushed 55bc6fa. Answering the CHANGES_REQUESTED review, and thanks for catching this one before it shipped.

The must-fix is done, taking your first option. Same-origin is exempt from the allow-list, which applies to cross-origin callers only. Your framing was the useful part: on main the same request was served, and agent-bff/README.md:97 promises "Empty ⇒ no cross-origin browser access" — with the exemption in place that sentence is exactly true again, so it needed no rewrite. Every BFF data route being a POST is what made this total rather than partial: a same-origin UI was 403ing on every list, count and action.

Matched on host rather than on origin === ctx.origin. Comparing the full origin looked cleaner but breaks behind a TLS-terminating proxy, where ctx.protocol reads http while the browser reports https — it would have passed in development and failed in production. Nothing is weakened: a caller able to forge Origin can simply omit it, which the allow-list lets through by design, and a genuine cross-site request never carries this host as its origin.

Macroscope then found two real holes in that first attempt, both now fixed in the same commit:

• new URL() drops a default port while ctx.host keeps it, so Host: app.example.com:443 against Origin: https://app.example.com 403ed — the exact case the exemption is for. Both spellings accepted, default port derived from the origin scheme; a non-default port still has to match exactly.
• the addBff()-after-start() guard keyed on a flag set at the end of start(), but mount() drains the onFirstStart hooks partway through, so an unawaited agent.start() followed by addBff() slipped past. Flag now set on the first line, cleared when startup fails.

Also fixed a doc claim my earlier hasAllRequired change falsified: the README said /health reports degraded without an encryption key. It reports configured.oauth: false and stays ok, since that key gates OAuth and not boot.

On your non-blocking note: the build workflow has now run on the head — everything green except LLM Integration Tests (ai-proxy), the stack-wide Anthropic-side failure you already identified.

Local: agent-bff 85 suites / 1440 tests, agent 88 / 1599, lint clean on both.

[macroscopeapp]

🟠 High cors/cors-middleware.ts:39

isSameOrigin treats Origin: http://app.example.com as same-origin with an HTTPS request to https://app.example.com/bff, allowing it to bypass the configured allow-list and reach downstream routes. Compare the origin scheme with the request's effective protocol as well as the host (including the proxy's forwarded protocol).

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

In file @packages/agent-bff/src/cors/cors-middleware.ts around line 39:

`isSameOrigin` treats `Origin: http://app.example.com` as same-origin with an HTTPS request to `https://app.example.com/bff`, allowing it to bypass the configured allow-list and reach downstream routes. Compare the origin scheme with the request's effective protocol as well as the host (including the proxy's forwarded protocol).

[nbouliol]

Not changing this — the scheme is left out deliberately, and the reason is in the comment above isSameOrigin.

Comparing it would break the common deployment rather than protect it: behind a TLS-terminating proxy the browser reports https while ctx.protocol stays http, so a scheme check passes in development and refuses every same-origin request in production. ctx.protocol only tells the truth when app.proxy is set and X-Forwarded-Proto survives the hop, neither of which this middleware can assume about a host application it is mounted into.

On the exposure itself: for a browser to send Origin: http://app.example.com to the HTTPS BFF, a page has to be served over plaintext on that same host — which needs either an attacker already on the network path or a listener on that host, and HSTS removes it for any site that sets it. That attacker does not gain a credential: the BFF is bearer-only, no cookies, so the forged-origin request carries no session unless the caller already holds the token. And the allow-list is not what stands between a cross-site page and this BFF — there the browser sets Origin to the attacking page, which the exemption never matches.

What is genuinely true, and worth stating rather than hiding: on a plaintext-reachable host, a http:// page can read BFF responses for requests it can already authenticate. Anyone who cannot accept that should name their origins in allowedOrigins and serve the UI cross-origin, which skips the exemption entirely.

Happy to revisit if you can show a path that does not require plaintext on the same host.

[Tonours]

Verified at 5a6593a. The must-fix is closed properly: the same-origin exemption matches on host, absorbing both normalizations new URL() and the raw Host header disagree on (default port spelled out or not, case) — a non-default port is still another origin and refused, and the whole class is pinned by unit tests on both sides plus the empty-allow-list same-origin POST case. The three open bot findings are closed too: /health stays ok without the encryption key (it gates OAuth, not boot — configured.oauth says what is off, and the env-table promise was resynced), metric tags reach the host logs, and addBff() past startup throws — hardened to mid-flight calls and failed starts, both tested. Approving.

Left open on purpose: the macroscopeapp thread on the scheme-mismatch in isSameOrigin — host-only matching is the documented tradeoff (TLS-terminating proxies; a forgeable Origin buys nothing over omitting it under bearer auth), but it is the author's call to answer.

[Tonours]

Verified at 5a6593a. The must-fix is closed properly: the same-origin exemption matches on host, absorbing both normalizations new URL() and the raw Host header disagree on (default port spelled out or not, case) — a non-default port is still another origin and refused, and the class is pinned by unit tests on both sides plus the empty-allow-list same-origin POST case. The three open bot findings are closed too: /health stays ok without the encryption key (it gates OAuth, not boot — configured.oauth says what is off, env-table promise resynced), metric tags reach the host logs, and addBff() past startup throws — hardened to mid-flight calls and failed starts, both tested. Approving.

Left open on purpose: the macroscopeapp thread on the scheme mismatch in isSameOrigin — host-only matching is the documented tradeoff (TLS-terminating proxies; a forgeable Origin buys nothing over omitting it under bearer auth), but it is the author's call to answer.