feat(gateway): release the forest gateway r1 by Tonours · Pull Request #1993 · ForestAdmin/agent-nodejs

Tonours · 2026-10-12T12:42:07Z

Merges the Forest Gateway R1 train into main: addGateway() on the agent, the standalone @forestadmin/gateway package (forest-gateway), service account credentials on the Gateway MCP, and the plan refusal surfaced by agent-bff.

fixes PRD-1333
fixes PRD-1334
fixes PRD-1337
fixes PRD-1353
fixes PRD-1354
fixes PRD-1372
fixes PRD-1374

What

Every change below was reviewed and approved in its own PR against feat/gateway-r1:

PR	Package	Change
#1964	agent	`addGateway()` as the single gateway entry point
#1967	agent	`addGateway()` served through the gateway switch
#1974	agent-bff	gateway allowlist applied to API OAuth
#1979	agent-bff	customer-facing naming becomes Gateway API
#1978	gateway (new)	MCP and API on one port, ghcr image published on release tag
#1944	forestadmin-client, mcp-server	service account credential (`fgw_` / `fbff_`) accepted on the MCP
#1985	agent-bff	sends `?service=api` on token exchanges, plan refusal becomes `403 plan_feature_missing`

main was merged into the train beforehand (18dac204b, no conflict). The conflicts of #1944 and #1985 with the train were resolved as unions on their branches.

Why

Squash-only repo: this PR lands as one commit, so multi-semantic-release bumps every touched package once (feat, minor) and publishes @forestadmin/gateway for the first time.
Server side: ForestAdmin/forestadmin-server#8575 (plan gates, flags off by default). Merging this PR first is safe, ?service=api is ignored by servers that do not validate the query.
Docs docs: document the embedded Forest Gateway docs#53 waits for the npm and ghcr publications, then the hosted API switch (ForestAdmin/forestadmin-server#8581).

How to test

CI of each PR on the train. Locally after the train sync, on the #1944 and #1985 merge results:

Package	Result
forestadmin-client	394/394
mcp-server	1576/1576, tsc clean
agent-bff	2265/2265, tsc clean
gateway	196/196, tsc clean

Real-stack proof of the service account on the MCP: trust bench gateway-mcp-sa (merge of #1978 + #1944 against #8575): PASS, baseline without #1944 answers 401.

Definition of Done

General

Write an explicit title for the Pull Request, following Conventional Commits specification
Test manually the implemented changes
Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

Consider the security impact of the changes made

https://claude.ai/code/session_0127TaBC6gYXxGAzzFRRfSt9

* feat(gateway): serve the MCP and the API on one port Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * ci: lint and test the gateway package Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(gateway): build against the workspace agent-bff and mcp-server Exact pins fall behind the workspace on each release, since a private package is skipped by multi-semantic-release, and Yarn then pulls the published versions instead of linking the local ones. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(mcp-server): export the listener variables parseMcpEnv reads Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(gateway): follow the listener variable names agent-bff and mcp-server own A rename on their side now fails the gateway's typecheck, or carries over through the exported name, instead of silently moving the API's public url and port. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(agent-bff): export the openapi --output handling for other CLIs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(gateway): reuse agent-bff's openapi --output handling Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(gateway): read one set of env vars, legacy names as aliases (#1980) * feat(gateway): warn that forest-mcp-server and forest-bff are deprecated (#1990) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* feat(mcp-server): accept a service account credential An fgw_ or fbff_ bearer is resolved on the Forest server with service mcp, cached, and turned into a short-lived agent token. The resolve client lives in forestadmin-client so mcp-server imports nothing from agent-bff. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(mcp-server): validate tags and log why a credential resolve failed Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(forestadmin-client): keep why a gateway key resolve was unreachable Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(mcp-server): sign the service account agent token in the shared claims shape Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: sim <sim@local>

…#1985) * feat(agent-bff): declare the api service and surface the plan refusal * fix(agent-bff): log the plan refusal as expected, with its reason * refactor(agent-bff): extract the session access failure mapping --------- Co-authored-by: sim <sim@local>

linear-code · 2026-10-12T12:42:17Z

qltysh · 2026-10-12T12:43:37Z

13 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 8): buildAgentMiddlewares	3
qlty	Structure	Function with many returns (count = 7): dispatchCli	3
qlty	Duplication	Found 47 lines of similar code in 2 locations (mass = 226)	3
qlty	Structure	Function with high complexity (count = 14): start	2
qlty	Structure	High total complexity (count = 65)	1
qlty	Structure	Complex binary expression	1

qltysh · 2026-10-12T12:49:30Z

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.1%.

Modified Files with Diff Coverage (42)

File	% Diff	Uncovered Line #s
packages/agent-bff/src/oauth/forest-server-client.ts	100.0%
packages/agent-bff/src/openapi/openapi-document.ts	100.0%
packages/agent-bff/src/oauth/oauth-routes.ts	100.0%
packages/agent-bff/src/http/bff-http-error.ts	100.0%
packages/agent/src/embedded-bff.ts	96.0%	57
packages/agent-bff/src/cli-dispatch.ts	100.0%
packages/agent-bff/src/config/missing-config-warning.ts	100.0%
packages/agent/src/agent.ts	100.0%
packages/agent-bff/src/oauth/session-lifecycle.ts	100.0%
packages/agent-bff/src/cors/cors-middleware.ts	100.0%
packages/agent-bff/src/api-key/api-key-error.ts	100.0%
packages/agent-bff/src/oauth/oauth-exchange-error.ts	100.0%
packages/agent-bff/src/auth/forest-server-token-middleware.ts	100.0%
packages/agent-bff/src/oauth/oauth-error.ts	100.0%
packages/agent-bff/src/build-bff.ts	100.0%
packages/agent-bff/src/config/env-config.ts	100.0%
packages/agent/src/bff-routes.ts	100.0%
packages/agent-bff/src/index.ts	100.0%
packages/agent-bff/src/cors/per-key-origin.ts	100.0%
packages/agent/src/framework-mounter.ts	100.0%
packages/agent-bff/src/openapi/render-openapi.ts	100.0%
packages/agent-bff/src/cli-output.ts	100.0%
packages/forestadmin-client/src/index.ts	100.0%
packages/agent/src/utils/express-to-koa.ts	100.0%
packages/gateway/src/env-aliases.ts	100.0%
packages/gateway/src/version.ts	100.0%
packages/gateway/src/cli-dispatch.ts	100.0%
packages/gateway/src/index.ts	100.0%
...stadmin-client/src/oauth-client-allowlist/is-client-allowed.ts	100.0%
packages/gateway/src/standalone-handler.ts	100.0%
packages/gateway/src/healthcheck.ts	100.0%
packages/gateway/src/gateway-env.ts	100.0%
...min-client/src/oauth-client-allowlist/normalize-domain-list.ts	50.0%	33
packages/gateway/src/run-gateway.ts	100.0%
packages/agent/src/gateway.ts	100.0%
packages/forestadmin-client/src/gateway-api-key/index.ts	100.0%
packages/forestadmin-client/src/gateway-api-key/resolve-error.ts	100.0%
packages/mcp-server/src/index.ts	100.0%
packages/mcp-server/src/mcp-env.ts	100.0%
packages/mcp-server/src/forest-oauth-provider.ts	100.0%
packages/mcp-server/src/server.ts	100.0%
packages/mcp-server/src/gateway-api-key-authenticator.ts	100.0%
Total	99.7%

🤖 Increase coverage with AI coding...

In the `feat/gateway-r1` branch, add test coverage for this new code:

- `packages/agent/src/embedded-bff.ts` -- Line 57
- `packages/forestadmin-client/src/oauth-client-allowlist/normalize-domain-list.ts` -- Line 33

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

nbouliol

Spec (PRD-1333, PRD-1334, PRD-1337, PRD-1353, PRD-1354, PRD-1372, PRD-1374): conforms, except the MCP discovery documents not answering 503 while the embedded Gateway starts, inline on gateway.ts:30.

Applies to: the PR as a whole
Claude Opus 5.5 (claude-opus-5-5): Should fix: a reader of addGateway cannot learn why the MCP and the API share one /oauth/* route, and no ADR records it.

Code

Customers register clients against <basePath>/oauth/*?service=api, the code never says why <basePath>/api/oauth/token was turned down, and docs/adr holds no Gateway record.

A way out: run /adr on the shared OAuth route and on addGateway superseding mountAiMcpServer, addBff and forest-bff.

Reproduction

Read agent.ts and gateway.ts for why OAuth is shared across services.
Search docs/adr for the Gateway, which returns no record.

nbouliol · 2026-10-12T13:01:34Z

@@ -1,9 +1,12 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import type { GatewayServices } from './gateway';


Claude Opus 5.5 (claude-opus-5-5): This pull request lands in files that keep accumulating debt, so refactor them, or open a ticket naming each file, before the next feature.

Files

packages/agent/src/agent.ts: 894 lines, 12 commits in 90 days, mixes lifecycle, datasource customization and embedded MCP, BFF and Gateway composition.

Split first: lines 366-625 and 739-793, the embedded-service composition, into its own module.

packages/agent-bff/src/build-bff.ts: 653 lines, 22 commits in 90 days, mixes body guards, the OAuth edge, the API-key edge and agent routes.

Split first: lines 305-552, the agent edge, into its own module.

packages/agent-bff/src/openapi/openapi-document.ts: 705 lines, 18 commits in 90 days, mixes the error-response catalog, the route table and document assembly.

Split first: lines 36-268, the error-response catalog, into its own module.

packages/agent-bff/src/openapi/unfolded-paths.ts: 786 lines, 11 commits in 90 days, mixes filter-schema derivation, request bodies and operation registration.

Split first: lines 106-265, the filter-schema derivation, into its own module.

Out of scope for the R1 release, which only merges already reviewed changes. Ticketed as PRD-1542, one sub-issue and one PR per file: PRD-1543 (agent.ts embedded-service composition), PRD-1544 (build-bff.ts agent edge), PRD-1545 (openapi-document.ts error catalog), PRD-1546 (unfolded-paths.ts filter-schema derivation). Each is a pure move, starting once this PR is merged.

nbouliol · 2026-10-12T13:01:34Z

+export { default as GatewayApiKeyResolveError } from './resolve-error';
+export type { GatewayApiKeyResolveErrorParams } from './resolve-error';
+
+const API_KEY_PATTERN = /^(?:fgw|fbff)_([0-9a-f]{16})_([0-9a-f]{64})$/;


Claude Opus 5.5 (claude-opus-5-5): Should fix: the next change to the key format or the resolve contract must land twice, or the API and the MCP accept different credentials.

Code

This file copies the key pattern, RESOLVE_PATH and the error mapping that agent-bff/src/api-key/api-key.ts:3 and api-key-client.ts still own.

A way out: keep forestadmin-client as the single home and have agent-bff's api-key-authenticator.ts consume GatewayApiKeyClient with service: 'api'.
Also moves: agent-bff's tests of api-key-client.ts and api-key.ts, and the hashApiKey copy in gateway-api-key-authenticator.ts:76.

Reproduction

Add a key prefix to API_KEY_PATTERN in this file only.

Send a key with that prefix to the Gateway MCP, which resolves it.

Send the same key to the Gateway API, which answers 401.

Agreed, and already ticketed: PRD-1409 moves agent-bff's resolve onto GatewayApiKeyClient (single key pattern, resolve path and error mapping, public agent-bff exports kept as re-exports). It was left out of #1944 on purpose (decided 2026-09-30) to keep this release scoped; not fixed in this PR.

Reopened: the two copies still stand at this head, and PRD-1409 tracks their merge outside this pull request.

How it was checked

Predicate: a key format or resolve contract defined in both forestadmin-client and agent-bff/src/api-key.
API_KEY_PATTERN still sits in both gateway-api-key/index.ts:6 and agent-bff/src/api-key/api-key.ts:3, untouched since the review.
PRD-1409 covers exactly this move, so the thread stays open until it lands or a reviewer accepts the deferral.

…ery while down

…sserts

Tonours · 2026-10-12T13:16:41Z

Review follow-up for the PR-level finding (no ADR for the shared OAuth route): recorded in c0f3658, docs/adr/2026-10-12-one-gateway-serves-the-mcp-and-the-api-behind-a-shared-oauth-route.md. It covers addGateway superseding mountAiMcpServer / addBff / forest-bff as deprecated aliases, why MCP and API share <basePath>/oauth/* told apart by ?service=api, and why <basePath>/api/oauth/* and registry-based routing were turned down.

nbouliol · 2026-10-12T13:24:56Z

Closed: docs/adr/2026-10-12-one-gateway-serves-the-mcp-and-the-api-behind-a-shared-oauth-route.md records the shared OAuth route.

How it was checked

Predicate: a reader who cannot learn why the MCP and the API share <basePath>/oauth/*.
The ADR names the ?service=api dispatch, the turned-down <basePath>/api/oauth/* and registry routing, and the deprecated aliases.
No test can pin a recorded decision, so this close stays unpinned.

nbouliol

Approved at 28c1702: the remaining API-key duplication finding is deferred to PRD-1409.

Tonours and others added 9 commits October 5, 2026 17:26

feat(agent): add addGateway() as the single gateway entry point (#1964)

0670c3a

feat(agent): serve addGateway() through the gateway switch (#1967)

5ba9cfe

feat(agent-bff): apply the gateway allowlist to API OAuth (#1974)

96baf20

feat(agent-bff): rename what the customer reads to Gateway API (#1979)

1a4fefc

chore: merge main into gateway train

52dadb5

chore: merge main into gateway train

18dac20

nbouliol reviewed Oct 12, 2026

View reviewed changes

sim added 3 commits October 12, 2026 15:16

fix(agent): validate the gateway allowlist early and claim mcp discov…

b97175b

…ery while down

test(agent-bff): name the gateway api 429 credit test after what it a…

a4aa5c7

…sserts

docs(adr): record the gateway shared oauth route

c0f3658

macroscopeapp Bot reviewed Oct 12, 2026

View reviewed changes

Comment thread packages/agent/src/gateway.ts Outdated

fix(agent): claim the gateway oauth route for the api service too

28c1702

macroscopeapp Bot reviewed Oct 12, 2026

View reviewed changes

Comment thread packages/agent/src/gateway.ts

nbouliol approved these changes Oct 12, 2026

View reviewed changes

		@@ -1,9 +1,12 @@
		/* eslint-disable @typescript-eslint/no-explicit-any */
		import type { GatewayServices } from './gateway';

Conversation

Tonours commented Oct 12, 2026

What

Why

How to test

Definition of Done

General

Security

Uh oh!

linear-code Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qltysh Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

13 new issues

Uh oh!

qltysh Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nbouliol left a comment

Choose a reason for hiding this comment

Uh oh!

nbouliol Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

Tonours Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nbouliol Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

Tonours Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

nbouliol Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Tonours commented Oct 12, 2026

Uh oh!

Uh oh!

Uh oh!

nbouliol commented Oct 12, 2026

Uh oh!

nbouliol left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

linear-code Bot commented Oct 12, 2026 •

edited

Loading

qltysh Bot commented Oct 12, 2026 •

edited

Loading

qltysh Bot commented Oct 12, 2026 •

edited

Loading

Tonours Oct 12, 2026 •

edited

Loading