feat(agent-bff): proxy the ai query on post /agent/v1/ai/query by Tonours · Pull Request #1845 · ForestAdmin/agent-nodejs

Tonours · 2026-08-24T17:07:22Z

fixes PRD-1033

What

POST /agent/v1/ai/query relays the body unchanged to /api/ai-proxy/ai-query, authenticated with the OAuth session the BFF already holds. Second half of PRD-944; GET /agent/v1/context shipped in #1838.

Why

After the OAuth switch the Zendesk app has no SaaS token left — it sends its bff_access to api.forestadmin.com, which rejects a JWT it never issued. The provider keys live on the SaaS, so this one route is a relay rather than a contract.

How

Outgoing headers are a closed allow-list built server-side: Authorization (session saasAccessToken via ensureFreshServerAccess), Content-Type, forest-environment-id, forest-rendering-id. Nothing incoming is copied — the SaaS prefers a session cookie over the Bearer (make-fetch-token.ts:26-30), and x-mcp-oauth-tokens is injected as Authorization toward an MCP server.
Upstream path is fixed. Never a dynamic :route.
Session required. An API key gets 403 oauth_required: it produces no sid, so there is no saasAccessToken to forward. A third-party app authenticating via OAuth will work with no code change.
1 MB body on this route only. A scoped parser mounted before the global one — @koa/bodyparser skips when ctx.request.body is set. Data routes keep 16 KB, /oauth/token keeps parsing. The global 16 KB breaks AI prompts past ~30 collections (measured).
No upstream body reaches the iframe unless it is JSON and below 500. A WAF answers HTML on 403/429; status is preserved, body replaced. Timeout → 504, bounded by BFF_AI_TIMEOUT_MS (default 120s) — nothing else on the chain bounds an AI generation today.
ai-name is a constant, not an env var: it selects the SaaS billing line and model, so a caller must not choose it.
The OpenAPI document publishes this path only when OAuth is configured, since that is the only case where the route is mounted. The forest-bff openapi export therefore omits it: it cannot know the runtime configuration.

Scope and safety

ALLOWED_HEADERS is deliberately unchanged. The forest-* headers the app sends today are exactly what the BFF now derives server-side; letting them through the preflight would mean proving we ignore them. The app drops them instead.

No body validation (the SaaS validates, and its schema is deliberately loose), no rate limiting, no session store change.

How to test

yarn workspace @forestadmin/agent-bff test   # 1250 tests
yarn workspace @forestadmin/agent-bff lint
yarn workspace @forestadmin/agent-bff build

Two tests exist only to catch a mount-order inversion, and both were verified to fail when the lines are swapped: "900 KB passes" (a 2 MB → 413 test does not catch it — both orders give 413), and the runCli test reaching the route without X-Forest-Timezone.

Known limitation

Not reachable from the Zendesk app until its own switch lands: fetchAIProxy still targets the SaaS and still sends forest-* headers, which this preflight rejects. Separate PR, same ticket.

Behind the BFF every user exits on one IP, so the SaaS per-IP anti-brute-force becomes a shared quota. Degrades cleanly (the 429 is relayed), worth watching in production.

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

linear-code · 2026-08-24T17:07:25Z

PRD-1033

qltysh · 2026-08-24T17:13:08Z

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (16)

File	% Diff	Uncovered Line #s
packages/agent-bff/src/openapi/openapi-document.ts	100.0%
packages/agent-bff/src/auth/auth-mode.ts	100.0%
packages/agent-bff/src/http/body-limit.ts	100.0%
packages/agent-bff/src/cli-dispatch.ts	100.0%
packages/agent-bff/src/oauth/session-lifecycle.ts	100.0%
packages/agent-bff/src/api-key/agent-token.ts	100.0%
packages/agent-bff/src/cli-core.ts	95.5%	73
packages/agent-bff/src/oauth/oauth-error.ts	100.0%
packages/agent-bff/src/config/env-config.ts	100.0%
packages/agent-bff/src/openapi/schemas.ts	100.0%
packages/agent-bff/src/openapi/unfolded-document.ts	100.0%
packages/agent-bff/src/openapi/openapi-routes.ts	100.0%
packages/agent-bff/src/http/bff-local-errors.ts	100.0%
packages/agent-bff/src/ai/ai-routes-middleware.ts	100.0%
packages/agent-bff/src/ai/ai-proxy-client.ts	100.0%
packages/agent-bff/src/ai/ai-proxy-timeout-error.ts	100.0%
Total	99.4%

🤖 Increase coverage with AI coding...

In the `feat/prd-1033-ai-query-proxy` branch, add test coverage for this new code:

- `packages/agent-bff/src/cli-core.ts` -- Line 73

🚦 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 · 2026-08-24T17:17:51Z

6 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): resolveSessionAccessToken	4
qlty	Structure	Function with many returns (count = 5): createOpenApiRoutes	2

nbouliol · 2026-08-25T15:15:27Z

+  const app = new Koa();
+
+  app.use(createErrorMiddleware({ logger: () => undefined }));
+  app.use(bodyParser({ jsonLimit: '1mb', enableTypes: ['json'] }));


Importing AI_BODY_LIMIT here instead of the literal would make the fixture track the real limit.

nbouliol · 2026-08-25T15:15:27Z

+          .post('/agent/v1/ai/query')
+          .set('Authorization', `Bearer ${sessionToken()}`)
+          .set('Content-Type', 'application/json')
+          .set('Content-Length', String(2 * 1024 * 1024))


This declares a length it never sends, so raw-body short-circuits on the header and the byte-counting path is never exercised; with the pass case at 900 KB, neither test sits at the boundary — a real ~1.05 MB body would cover both sides.

nbouliol · 2026-08-25T15:15:27Z

+    it('should target the fixed ai-query path with the ai-name of this deployment', async () => {
+      await makeClient().query(params());
+
+      expect(firstCall()[0]).toBe(`${FOREST_SERVER_URL}/api/ai-proxy/ai-query?ai-name=zendesk`);


What about a POST /agent/v1/ai/query?ai-name=other case asserting the outgoing URL still carries zendesk? Both ctx.path comparisons would break silently on a refactor to ctx.url.

nbouliol · 2026-08-25T15:15:27Z

+export const AI_QUERY_ROUTE = '/agent/v1/ai/query';
+
+const JSON_CONTENT_TYPE = 'application/json';
+const MAX_CAUSE_DEPTH = 3;


No test walks a cause chain deeper than 3, so nothing proves the recursion actually stops.

nbouliol · 2026-08-25T15:15:27Z

      'deployment runs without the OAuth configuration.',
  });

+export const AiQueryRequestSchema = z


Nothing validates against this, yet the served contract now carries a BFF-authored shape nobody will keep in sync with routeArgsSchema — z.unknown(), as used for the 200, would match the passthrough decision.

nbouliol · 2026-08-25T15:15:27Z


+  describe('BFF_AI_TIMEOUT_MS', () => {
+    it('should default to 2 minutes when unset, since an AI generation is slow', () => {
+      expect(parseConfig({ ...VALID_ENV }).aiTimeoutMs).toBe(120_000);


DEFAULT_AI_TIMEOUT_MS is already imported and used three cases below — using it here too keeps the default in one place.

nbouliol · 2026-08-25T15:15:27Z

    });

+    it('should not mount the AI query route without the OAuth configuration, since it has no session', async () => {
+      const token = jsonwebtoken.sign(


A sessionToken() helper already exists in the sibling describe — reusing it drops three copies of this block.

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

… row

…ract

… flake

feat(agent-bff): proxy the ai query on post /agent/v1/ai/query

493c603

macroscopeapp Bot reviewed Aug 24, 2026

View reviewed changes

Comment thread packages/agent-bff/src/ai/ai-proxy-client.ts Outdated

Comment thread packages/agent-bff/src/openapi/openapi-document.ts Outdated

fix(agent-bff): match content-type case and gate the ai path on oauth

d172557

macroscopeapp Bot reviewed Aug 24, 2026

View reviewed changes

Comment thread packages/agent-bff/src/ai/ai-proxy-client.ts Outdated

Tonours added 8 commits August 24, 2026 19:19

test(agent-bff): pin the ai path publication to a mounted route

2b13cfb

fix(agent-bff): raise a timeout when the body read aborts

37fb0b1

refactor(agent-bff): name the error file after its class

682fa0b

refactor(agent-bff): name the timeout ceiling for both variables

65e2b99

refactor(agent-bff): move requireRenderingId to the auth layer

9bd1e09

fix(agent-bff): log ai relay failures and relay json exactly

c769350

fix(agent-bff): document and publish the ai path from oauth config

eb47b43

docs(agent-bff): document the ai query relay in the readme

be29719

macroscopeapp Bot reviewed Aug 25, 2026

View reviewed changes

Comment thread packages/agent-bff/README.md

nbouliol reviewed Aug 25, 2026

View reviewed changes

Tonours and others added 4 commits August 25, 2026 17:21

docs(agent-bff): qualify the status kept on a non-json upstream answer

bf7e48c

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

docs(agent-bff): restore the bullet indentation and the timeout table…

399bd62

… row

fix(agent-bff): leave the ai query request body free-form in the cont…

296846c

…ract

test(agent-bff): pin the outgoing ai-name and stop the oversized-body…

55fce99

… flake

Tonours force-pushed the feat/prd-1033-ai-query-proxy branch from ad383e2 to 55fce99 Compare August 25, 2026 15:38

macroscopeapp Bot reviewed Aug 25, 2026

View reviewed changes

Comment thread packages/agent-bff/README.md

docs(agent-bff): scope the timezone bypass to the mounted routes

0b066ca

Tonours mentioned this pull request Aug 25, 2026

fix(agent-bff): advertise mode 1 on the data and action routes #1850

Open

4 tasks

Navigation Menu

Uh oh!

feat(agent-bff): proxy the ai query on post /agent/v1/ai/query - #1845

feat(agent-bff): proxy the ai query on post /agent/v1/ai/query#1845
Tonours wants to merge 15 commits into
mainfrom
feat/prd-1033-ai-query-proxy

Tonours commented Aug 24, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Aug 24, 2026

Uh oh!

Uh oh!

Uh oh!

qltysh Bot commented Aug 24, 2026 •

edited

Loading

Uh oh!

qltysh Bot commented Aug 24, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

nbouliol Aug 25, 2026

Uh oh!

nbouliol Aug 25, 2026

Uh oh!

nbouliol Aug 25, 2026

Uh oh!

nbouliol Aug 25, 2026

Uh oh!

nbouliol Aug 25, 2026

Uh oh!

nbouliol Aug 25, 2026

Uh oh!

nbouliol Aug 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

What

Why

How

Scope and safety

How to test

Known limitation

Definition of Done

General

Security

Uh oh!

linear-code Bot commented Aug 24, 2026

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Tonours commented Aug 24, 2026 •

edited

Loading

qltysh Bot commented Aug 24, 2026 •

edited

Loading

qltysh Bot commented Aug 24, 2026 •

edited

Loading