@forestadmin/agent 1.99.2 → 1.100.1

package/dist/embedded-bff.js

@@ -0,0 +1,220 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const bff_routes_1 = require("./bff-routes");
+/**
+ * Serialize the BFF's structured log context onto the message: the agent's logger only accepts an
+ * Error as its third argument, so the context would be dropped otherwise. Errors are unfolded by
+ * hand — their `message` and `stack` are not enumerable, so `JSON.stringify` alone turns the one
+ * value worth logging into `{}`. Never throws — logging must not break a request.
+ */
+function formatLog(message, context) {
+    if (!context || Object.keys(context).length === 0)
+        return `[BFF] ${message}`;
+    try {
+        const serialized = JSON.stringify(context, (_key, value) => value instanceof Error
+            ? { name: value.name, message: value.message, stack: value.stack }
+            : value);
+        return `[BFF] ${message} ${serialized}`;
+    }
+    catch {
+        return `[BFF] ${message} [unserializable context]`;
+    }
+}
+/**
+ * Owns the lifecycle of a BFF embedded in the agent process: configuration, dynamic loading of the
+ * optional package, build, and the request handler the agent mounts at `/bff`. The agent only wires
+ * the callback and delegates start/stop.
+ */
+class EmbeddedBff {
+    constructor(options, embedOptions) {
+        this.options = options;
+        this.embedOptions = embedOptions;
+        this.config = null;
+        this.bff = null;
+        this.stopped = false;
+        /**
+         * The callback the agent registers at `/bff`. Answers 503 rather than falling through while the
+         * BFF is not serving: a 404 from the host would read as "wrong url" instead of "not available".
+         * Boot and shutdown are told apart, because a probe should wait on the first and drain on the
+         * second.
+         */
+        this.handle = (req, res) => {
+            if (!this.bff) {
+                const type = this.stopped ? 'bff_stopped' : 'bff_not_started';
+                const message = this.stopped
+                    ? 'The embedded BFF was stopped with the agent.'
+                    : 'The embedded BFF is not started yet.';
+                res.statusCode = 503;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify({ error: { type, status: 503, message } }));
+                return;
+            }
+            // The BFF knows nothing of the prefix it is served under. `originalUrl` is claimed before the
+            // rewrite so a host logger reading it still reports the url the client asked for.
+            const bffReq = req;
+            bffReq.originalUrl ?? (bffReq.originalUrl = bffReq.url);
+            req.url = (0, bff_routes_1.stripBffPrefix)(req.url ?? bff_routes_1.BFF_PREFIX);
+            this.bff.callback(req, res);
+        };
+    }
+    /**
+     * Load the package and validate the options the caller handed to `addBff()`. Called before the
+     * agent mounts anything: everything checked here is caller input, and `parseConfig` throws on a
+     * mistyped `tokenEncryptionKey`, timezone, timeout or url. Failing here leaves nothing serving,
+     * where failing after mount() would leave the host with a live `/forest` and a bricked `/bff`.
+     */
+    async prepare() {
+        const { parseConfig, IN_PROCESS_AGENT_URL } = await this.importPackage();
+        const { embedOptions } = this;
+        this.config = parseConfig({
+            FOREST_AUTH_SECRET: this.options.authSecret,
+            FOREST_ENV_SECRET: this.options.envSecret,
+            FOREST_SERVER_URL: this.options.forestServerUrl,
+            FOREST_APP_URL: this.options.forestAppUrl,
+            // Names where the agent answers, never how it is reached: the dispatcher is the transport.
+            AGENT_URL: IN_PROCESS_AGENT_URL,
+            BFF_TOKEN_ENCRYPTION_KEY: embedOptions.tokenEncryptionKey,
+            BFF_ALLOWED_ORIGINS: embedOptions.allowedOrigins?.join(','),
+            BFF_DEFAULT_TIMEZONE: embedOptions.defaultTimezone,
+            BFF_AGENT_TIMEOUT_MS: embedOptions.agentTimeoutMs?.toString(),
+            BFF_AI_TIMEOUT_MS: embedOptions.aiTimeoutMs?.toString(),
+            // Off unless asked for: the document is not filtered per caller, so mounting a BFF must not
+            // publish the name of every exposed collection and field on an already-open port.
+            BFF_OPENAPI_ENABLED: String(embedOptions.openapiEnabled ?? false),
+        });
+    }
+    /**
+     * Build the BFF. Called from agent.start() after mount(), because the dispatcher only reaches the
+     * agent's own stack once that stack is mounted.
+     */
+    async start(dispatcher) {
+        if (!this.config)
+            await this.prepare();
+        // Cleared before the await, not after it: a start() following a stop() has to drop the previous
+        // shutdown's flag, while a stop() landing DURING the await must still be seen by the guard below.
+        this.stopped = false;
+        const { buildBff } = await this.importPackage();
+        const bff = await buildBff({
+            config: this.config,
+            dispatcher,
+            basePath: bff_routes_1.BFF_PREFIX,
+            // Counters are the schema cache's and the action-endpoint resolver's only channel — they take
+            // no logger — and every one of them reports a failure, so they go to the host's logs. Gauges
+            // do not: they are periodic cache sizes, and the default console sink reports them at Info,
+            // which would flood a host that only asked for a BFF.
+            metrics: {
+                // Tags carried through: `action_endpoint_error` and `action_endpoint_miss` name the
+                // rendering, collection and action that failed, which is the whole of what makes the line
+                // actionable — the metric name alone says only that something, somewhere, did not resolve.
+                increment: (name, tags) => this.options.logger('Warn', formatLog(`metric ${name}`, tags)),
+                gauge: () => undefined,
+            },
+            logger: (level, message, context) => this.options.logger(level, formatLog(message, context)),
+        });
+        // stop() may have landed while buildBff() was in flight. Assigning anyway would resurrect a
+        // stopped agent's /bff — dispatching into the stack it just tore down instead of answering 503.
+        if (this.stopped)
+            return;
+        this.bff = bff;
+        this.options.logger('Info', formatLog(`Embedded BFF mounted on ${bff_routes_1.BFF_PREFIX}`));
+        await this.warnIfExemptFromIpWhitelist();
+    }
+    /**
+     * The whitelist exempts a caller arriving over a loopback socket with no proxy hop, which is
+     * exactly what the in-process transport looks like — so every BFF request escapes it. That is the
+     * decision, not an oversight: propagating the caller's ip would make the embedded mode stricter
+     * than the standalone one, where the whitelist only ever sees the BFF's own host, and would refuse
+     * the browsers a third-party UI is made of. What it must not be is silent — an operator who turned
+     * the whitelist on to close a door has no other way to learn this door is not part of it.
+     *
+     * Reads the configuration itself rather than borrowing the one `IpWhitelist` already fetched: that
+     * route keeps it private, and reaching into it would put BFF concerns in an unrelated part of the
+     * agent. Costs one round-trip at boot. Never fails the boot: a warning is not worth refusing to
+     * serve over, and this is the same posture as the rest of the BFF's startup.
+     */
+    async warnIfExemptFromIpWhitelist() {
+        try {
+            const { isFeatureEnabled } = await this.options.forestAdminClient.getIpWhitelistConfiguration();
+            if (!isFeatureEnabled)
+                return;
+            this.options.logger('Warn', formatLog(`The IP whitelist is enabled for this environment, but requests served under ` +
+                `${bff_routes_1.BFF_PREFIX} are not subject to it: they reach the agent in-process, which the ` +
+                `whitelist exempts as a trusted loopback caller. A resolved API key or a valid OAuth ` +
+                `session is still required.`));
+        }
+        catch (error) {
+            this.options.logger('Debug', formatLog('Could not read the IP whitelist configuration', {
+                cause: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    /** Drop what the BFF read from the SaaS. Called on a restart, which means the schema moved. */
+    invalidate() {
+        this.bff?.invalidate();
+    }
+    /**
+     * Stop answering. The host application keeps whatever middleware it registered, so without this
+     * a stopped agent would go on serving BFF data through a dispatcher pointing at a dead stack.
+     */
+    stop() {
+        this.bff = null;
+        this.stopped = true;
+    }
+    /**
+     * Dynamically load the optional @forestadmin/agent-bff package. Deferred so agents that embed no
+     * BFF never load its code at startup.
+     */
+    async importPackage() {
+        try {
+            return await Promise.resolve().then(() => __importStar(require('@forestadmin/agent-bff')));
+        }
+        catch (error) {
+            // The original reason is kept: the package resolves from the host's own node_modules, so this
+            // also fires on a broken transitive dependency, a SyntaxError from a partial install, or a
+            // throw during the package's own evaluation — none of which "install it" would fix.
+            const { message } = error;
+            const wrapped = new Error(`The embedded BFF requires the \`@forestadmin/agent-bff\` package, which failed to ` +
+                `load: ${message}. Install it with \`npm install @forestadmin/agent-bff\`.`);
+            // Assigned rather than passed to the constructor: the repo targets ES2020, whose lib types no
+            // options bag on Error. A plain assignment carries the cause on every runtime, and the reason
+            // is in the message regardless of what reads it.
+            wrapped.cause = error;
+            throw wrapped;
+        }
+    }
+}
+exports.default = EmbeddedBff;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW1iZWRkZWQtYmZmLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2VtYmVkZGVkLWJmZi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztBQUdBLDZDQUEwRDtBQUUxRDs7Ozs7R0FLRztBQUNILFNBQVMsU0FBUyxDQUFDLE9BQWUsRUFBRSxPQUFpQztJQUNuRSxJQUFJLENBQUMsT0FBTyxJQUFJLE1BQU0sQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLENBQUMsTUFBTSxLQUFLLENBQUM7UUFBRSxPQUFPLFNBQVMsT0FBTyxFQUFFLENBQUM7SUFFN0UsSUFBSSxDQUFDO1FBQ0gsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDLFNBQVMsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FDekQsS0FBSyxZQUFZLEtBQUs7WUFDcEIsQ0FBQyxDQUFDLEVBQUUsSUFBSSxFQUFFLEtBQUssQ0FBQyxJQUFJLEVBQUUsT0FBTyxFQUFFLEtBQUssQ0FBQyxPQUFPLEVBQUUsS0FBSyxFQUFFLEtBQUssQ0FBQyxLQUFLLEVBQUU7WUFDbEUsQ0FBQyxDQUFDLEtBQUssQ0FDVixDQUFDO1FBRUYsT0FBTyxTQUFTLE9BQU8sSUFBSSxVQUFVLEVBQUUsQ0FBQztJQUMxQyxDQUFDO0lBQUMsTUFBTSxDQUFDO1FBQ1AsT0FBTyxTQUFTLE9BQU8sMkJBQTJCLENBQUM7SUFDckQsQ0FBQztBQUNILENBQUM7QUFFRDs7OztHQUlHO0FBQ0gsTUFBcUIsV0FBVztJQUs5QixZQUNtQixPQUFpQyxFQUNqQyxZQUE2QjtRQUQ3QixZQUFPLEdBQVAsT0FBTyxDQUEwQjtRQUNqQyxpQkFBWSxHQUFaLFlBQVksQ0FBaUI7UUFOeEMsV0FBTSxHQUFxQixJQUFJLENBQUM7UUFDaEMsUUFBRyxHQUFlLElBQUksQ0FBQztRQUN2QixZQUFPLEdBQUcsS0FBSyxDQUFDO1FBa0l4Qjs7Ozs7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

package/dist/framework-mounter.d.ts

@@ -1,4 +1,4 @@
-import type { HttpCallback, McpRouteMatcher } from './types';
+import type { HttpCallback, RootHandler } from './types';
 import type { Logger } from '@forestadmin/datasource-toolkit';
 import Router from '@koa/router';
 import InProcessDispatcher from './mcp-in-process-dispatcher';
@@ -11,16 +11,20 @@ export default class FrameworkMounter {
     protected readonly prefix: string;
     private readonly logger;
     private readonly fastifyAdapter;
-    private readonly mcpMiddleware;
+    private readonly rootMiddleware;
     private readonly inProcessDispatcher;
     private inProcessHookRegistered;
     /** Compute the prefix that the main router should be mounted at in the client's application */
     private get completeMountPrefix();
     constructor(prefix: string, logger: Logger);
     /**
-     * Set the MCP HTTP callback. Call this before mount() or remount().
+     * Register the MCP server at the root of the host application, or `null` to unregister it. The
+     * matcher comes with the callback: there is no default pattern set, so nothing can claim host
+     * urls by accident. Call this before mount() or remount().
      */
-    protected setMcpCallback(callback: HttpCallback | null, routeMatcher?: McpRouteMatcher): void;
+    protected setMcpCallback(handler: RootHandler | null): void;
+    /** Serve an embedded BFF at `/bff`. Pass null to stop answering there. */
+    protected setBffCallback(callback: HttpCallback | null): void;
     /**
      * Dispatcher that runs agent-client requests against the agent's own `/forest` stack in-memory.
      * The handler is rebuilt on every (re)mount so a captured reference never goes stale.

package/dist/framework-mounter.js

@@ -7,9 +7,10 @@ const router_1 = __importDefault(require("@koa/router"));
 const http_1 = require("http");
 const koa_1 = __importDefault(require("koa"));
 const path_1 = __importDefault(require("path"));
+const bff_routes_1 = require("./bff-routes");
 const fastify_adapter_1 = __importDefault(require("./fastify-adapter"));
 const mcp_in_process_dispatcher_1 = __importDefault(require("./mcp-in-process-dispatcher"));
-const mcp_middleware_1 = __importDefault(require("./mcp-middleware"));
+const root_middleware_1 = __importDefault(require("./root-middleware"));
 class FrameworkMounter {
     /** Compute the prefix that the main router should be mounted at in the client's application */
     get completeMountPrefix() {
@@ -23,14 +24,20 @@ class FrameworkMounter {
         this.prefix = prefix;
         this.logger = logger;
         this.fastifyAdapter = new fastify_adapter_1.default(logger);
-        this.mcpMiddleware = new mcp_middleware_1.default();
+        this.rootMiddleware = new root_middleware_1.default(logger);
         this.inProcessDispatcher = new mcp_in_process_dispatcher_1.default(logger);
     }
     /**
-     * Set the MCP HTTP callback. Call this before mount() or remount().
+     * Register the MCP server at the root of the host application, or `null` to unregister it. The
+     * matcher comes with the callback: there is no default pattern set, so nothing can claim host
+     * urls by accident. Call this before mount() or remount().
      */
-    setMcpCallback(callback, routeMatcher) {
-        this.mcpMiddleware.setCallback(callback, routeMatcher);
+    setMcpCallback(handler) {
+        this.rootMiddleware.set('mcp', handler);
+    }
+    /** Serve an embedded BFF at `/bff`. Pass null to stop answering there. */
+    setBffCallback(callback) {
+        this.rootMiddleware.set('bff', callback && { callback, matches: bff_routes_1.isBffRoute });
     }
     /**
      * Dispatcher that runs agent-client requests against the agent's own `/forest` stack in-memory.
@@ -101,7 +108,7 @@ class FrameworkMounter {
      */
     mountOnExpress(express) {
         // MCP middleware - the callback handles its own path filtering and calls next() for non-MCP routes
-        express.use(this.mcpMiddleware.getExpressMiddleware());
+        express.use(this.rootMiddleware.getExpressMiddleware());
         // Mount main forest routes at /{prefix}/forest
         express.use(this.completeMountPrefix, this.getConnectCallback(false));
         this.logger('Info', `Successfully mounted on Express.js`);
@@ -113,7 +120,7 @@ class FrameworkMounter {
      */
     mountOnFastify(fastify) {
         // MCP middleware at root - the callback handles its own path filtering
-        this.fastifyAdapter.useCallback(fastify, this.mcpMiddleware.getExpressMiddleware(), '/');
+        this.fastifyAdapter.useCallback(fastify, this.rootMiddleware.getExpressMiddleware(), '/');
         // Mount main forest routes
         const callback = this.getConnectCallback(false);
         this.fastifyAdapter.useCallback(fastify, callback, this.completeMountPrefix);
@@ -138,7 +145,7 @@ class FrameworkMounter {
             parentRouter.use(driverRouter.routes());
         });
         // MCP middleware - intercepts MCP routes before they reach Koa's body parser
-        koa.use(this.mcpMiddleware.getKoaMiddleware());
+        koa.use(this.rootMiddleware.getKoaMiddleware());
         koa.use(parentRouter.routes());
         this.logger('Info', `Successfully mounted on Koa`);
         return this;
@@ -152,13 +159,13 @@ class FrameworkMounter {
         const callback = this.getConnectCallback(false);
         if (adapter.constructor.name === 'ExpressAdapter') {
             // MCP middleware at root - the callback handles its own path filtering
-            nestJs.use(this.mcpMiddleware.getExpressMiddleware());
+            nestJs.use(this.rootMiddleware.getExpressMiddleware());
             // Mount main forest routes
             nestJs.use(this.completeMountPrefix, callback);
         }
         else {
             // Fastify adapter - MCP middleware at root
-            this.fastifyAdapter.useCallback(nestJs, this.mcpMiddleware.getExpressMiddleware(), '/');
+            this.fastifyAdapter.useCallback(nestJs, this.rootMiddleware.getExpressMiddleware(), '/');
             this.fastifyAdapter.useCallback(nestJs, callback, this.completeMountPrefix);
         }
         this.logger('Info', `Successfully mounted on NestJS`);
@@ -176,9 +183,9 @@ class FrameworkMounter {
         return (req, res) => {
             // For standalone server (nested), check MCP callback first
             // The MCP callback handles its own path filtering
-            const mcpCallback = this.mcpMiddleware.getCallback();
-            if (nested && mcpCallback) {
-                mcpCallback(req, res, () => {
+            const rootCallback = this.rootMiddleware.getCallback();
+            if (nested && rootCallback) {
+                rootCallback(req, res, () => {
                     // next() called means not an MCP route - forward to main handler
                     if (handler) {
                         handler(req, res);
@@ -201,4 +208,4 @@ class FrameworkMounter {
     }
 }
 exports.default = FrameworkMounter;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZnJhbWV3b3JrLW1vdW50ZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvZnJhbWV3b3JrLW1vdW50ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFLQSx5REFBaUM7QUFDakMsK0JBQW9DO0FBQ3BDLDhDQUFzQjtBQUN0QixnREFBd0I7QUFFeEIsd0VBQStDO0FBQy9DLDRGQUE4RDtBQUM5RCxzRUFBNkM7QUFFN0MsTUFBcUIsZ0JBQWdCO0lBZ0JuQywrRkFBK0Y7SUFDL0YsSUFBWSxtQkFBbUI7UUFDN0IsT0FBTyxjQUFJLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxHQUFHLEVBQUUsSUFBSSxDQUFDLE1BQU0sRUFBRSxRQUFRLENBQUMsQ0FBQztJQUNyRCxDQUFDO0lBRUQsWUFBWSxNQUFjLEVBQUUsTUFBYztRQWpCekIsaUJBQVksR0FBNEIsRUFBRSxDQUFDO1FBQzNDLGdCQUFXLEdBQTBDLEVBQUUsQ0FBQztRQUV4RCxXQUFNLEdBQTRCLEVBQUUsQ0FBQztRQU85Qyw0QkFBdUIsR0FBRyxLQUFLLENBQUM7UUFRdEMsSUFBSSxDQUFDLE1BQU0sR0FBRyxNQUFNLENBQUM7UUFDckIsSUFBSSxDQUFDLE1BQU0sR0FBRyxNQUFNLENBQUM7UUFDckIsSUFBSSxDQUFDLGNBQWMsR0FBRyxJQUFJLHlCQUFjLENBQUMsTUFBTSxDQUFDLENBQUM7UUFDakQsSUFBSSxDQUFDLGFBQWEsR0FBRyxJQUFJLHdCQUFhLEVBQUUsQ0FBQztRQUN6QyxJQUFJLENBQUMsbUJBQW1CLEdBQUcsSUFBSSxtQ0FBbUIsQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUM3RCxDQUFDO0lBRUQ7O09BRUc7SUFDTyxjQUFjLENBQUMsUUFBNkIsRUFBRSxZQUE4QjtRQUNwRixJQUFJLENBQUMsYUFBYSxDQUFDLFdBQVcsQ0FBQyxRQUFRLEVBQUUsWUFBWSxDQUFDLENBQUM7SUFDekQsQ0FBQztJQUVEOzs7T0FHRztJQUNPLHNCQUFzQjtRQUM5QixJQUFJ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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZnJhbWV3b3JrLW1vdW50ZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvZnJhbWV3b3JrLW1vdW50ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFLQSx5REFBaUM7QUFDakMsK0JBQW9DO0FBQ3BDLDhDQUFzQjtBQUN0QixnREFBd0I7QUFFeEIsNkNBQTBDO0FBQzFDLHdFQUErQztBQUMvQyw0RkFBOEQ7QUFDOUQsd0VBQStDO0FBRS9DLE1BQXFCLGdCQUFnQjtJQWdCbkMsK0ZBQStGO0lBQy9GLElBQVksbUJBQW1CO1FBQzdCLE9BQU8sY0FBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsR0FBRyxFQUFFLElBQUksQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLENBQUM7SUFDckQsQ0FBQztJQUVELFlBQVksTUFBYyxFQUFFLE1BQWM7UUFqQnpCLGlCQUFZLEdBQTRCLEVBQUUsQ0FBQztRQUMzQyxnQkFBVyxHQUEwQyxFQUFFLENBQUM7UUFFeEQsV0FBTSxHQUE0QixFQUFFLENBQUM7UUFPOUMsNEJBQXVCLEdBQUcsS0FBSyxDQUFDO1FBUXRDLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO1FBQ3JCLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO1FBQ3JCLElBQUksQ0FBQyxjQUFjLEdBQUcsSUFBSSx5QkFBYyxDQUFDLE1BQU0sQ0FBQyxDQUFDO1FBQ2pELElBQUksQ0FBQyxjQUFjLEdBQUcsSUFBSSx5QkFBYyxDQUFDLE1BQU0sQ0FBQyxDQUFDO1FBQ2pELElBQUksQ0FBQyxtQkFBbUIsR0FBRyxJQUFJLG1DQUFtQixDQUFDLE1BQU0sQ0FBQyxDQUFDO0lBQzdELENBQUM7SUFFRDs7OztPQUlHO0lBQ08sY0FBYyxDQUFDLE9BQTJCO1FBQ2xELElBQUksQ0FBQyxjQUFjLENBQUMsR0FBRyxDQUFDLEtBQUssRUFBRSxPQUFPLENBQUMsQ0FBQztJQUMxQyxDQUFDO0lBRUQsMEVBQTBFO0lBQ2hFLGNB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

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import type { TSchema } from '@forestadmin/datasource-customizer';
 import Agent from './agent';
 export declare function createAgent<S extends TSchema = TSchema>(options: AgentOptions): Agent<S>;
 export { Agent };
-export { AgentOptions, WorkflowExecutorEmbedOptions } from './types';
+export { AgentOptions, BffEmbedOptions, WorkflowExecutorEmbedOptions } from './types';
 export * from '@forestadmin/datasource-customizer';
 export { default as SchemaGenerator } from './utils/forest-schema/generator';
 //# sourceMappingURL=index.d.ts.map

package/dist/root-middleware.d.ts

@@ -0,0 +1,33 @@
+import type { HttpCallback, RootHandler } from './types';
+import type { Logger } from '@forestadmin/datasource-toolkit';
+import type Koa from 'koa';
+/**
+ * Handlers the agent serves at the root of the host application rather than under its own router
+ * prefix — the MCP server, the embedded BFF. Each one claims a set of paths through its matcher;
+ * anything else falls through to the host, untouched.
+ *
+ * Registered by name so a handler can be replaced or removed on a restart without the mount points
+ * having to know what is registered.
+ */
+export default class RootMiddleware {
+    private readonly handlers;
+    private readonly logger;
+    constructor(logger: Logger);
+    set(name: string, handler: RootHandler | null): void;
+    private entryFor;
+    /**
+     * First registered matcher wins. Overlapping matchers cannot be caught at registration — the
+     * predicates are opaque — so the winner is named here instead: a request answered by the wrong
+     * handler is otherwise indistinguishable from one whose route was never registered.
+     */
+    private handlerFor;
+    /**
+     * Connect-style middleware. A handler that decides not to answer calls `next()`, which passes the
+     * request on to the host exactly as if nothing had been registered.
+     */
+    getExpressMiddleware(): HttpCallback;
+    getKoaMiddleware(): Koa.Middleware;
+    /** The combined callback, or null when nothing is registered and the host needs no detour. */
+    getCallback(): HttpCallback | null;
+}
+//# sourceMappingURL=root-middleware.d.ts.map

package/dist/root-middleware.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_to_koa_1 = __importDefault(require("./utils/express-to-koa"));
+/**
+ * Handlers the agent serves at the root of the host application rather than under its own router
+ * prefix — the MCP server, the embedded BFF. Each one claims a set of paths through its matcher;
+ * anything else falls through to the host, untouched.
+ *
+ * Registered by name so a handler can be replaced or removed on a restart without the mount points
+ * having to know what is registered.
+ */
+class RootMiddleware {
+    constructor(logger) {
+        this.handlers = new Map();
+        this.logger = logger;
+    }
+    set(name, handler) {
+        if (handler)
+            this.handlers.set(name, handler);
+        else
+            this.handlers.delete(name);
+    }
+    entryFor(url) {
+        for (const entry of this.handlers) {
+            if (entry[1].matches(url))
+                return entry;
+        }
+        return null;
+    }
+    /**
+     * First registered matcher wins. Overlapping matchers cannot be caught at registration — the
+     * predicates are opaque — so the winner is named here instead: a request answered by the wrong
+     * handler is otherwise indistinguishable from one whose route was never registered.
+     */
+    handlerFor(url) {
+        const entry = this.entryFor(url);
+        if (!entry)
+            return null;
+        this.logger('Debug', `Root middleware: '${entry[0]}' claims ${url}`);
+        return entry[1].callback;
+    }
+    /**
+     * Connect-style middleware. A handler that decides not to answer calls `next()`, which passes the
+     * request on to the host exactly as if nothing had been registered.
+     */
+    getExpressMiddleware() {
+        return (req, res, next) => {
+            const handler = this.handlerFor(req.url ?? '/');
+            if (handler) {
+                handler(req, res, next);
+                return;
+            }
+            next?.();
+        };
+    }
+    getKoaMiddleware() {
+        return (0, express_to_koa_1.default)(this.getExpressMiddleware(), url => this.entryFor(url) !== null);
+    }
+    /** The combined callback, or null when nothing is registered and the host needs no detour. */
+    getCallback() {
+        if (this.handlers.size === 0)
+            return null;
+        return this.getExpressMiddleware();
+    }
+}
+exports.default = RootMiddleware;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicm9vdC1taWRkbGV3YXJlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3Jvb3QtbWlkZGxld2FyZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQUlBLDRFQUFrRDtBQUVsRDs7Ozs7OztHQU9HO0FBQ0gsTUFBcUIsY0FBYztJQUlqQyxZQUFZLE1BQWM7UUFIVCxhQUFRLEdBQUcsSUFBSSxHQUFHLEVBQXVCLENBQUM7UUFJekQsSUFBSSxDQUFDLE1BQU0sR0FBRyxNQUFNLENBQUM7SUFDdkIsQ0FBQztJQUVELEdBQUcsQ0FBQyxJQUFZLEVBQUUsT0FBMkI7UUFDM0MsSUFBSSxPQUFPO1lBQUUsSUFBSSxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsSUFBSSxFQUFFLE9BQU8sQ0FBQyxDQUFDOztZQUN6QyxJQUFJLENBQUMsUUFBUSxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUNsQyxDQUFDO0lBRU8sUUFBUSxDQUFDLEdBQVc7UUFDMUIsS0FBSyxNQUFNLEtBQUssSUFBSSxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDbEMsSUFBSSxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQztnQkFBRSxPQUFPLEtBQUssQ0FBQztRQUMxQyxDQUFDO1FBRUQsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNLLFVBQVUsQ0FBQyxHQUFXO1FBQzVCLE1BQU0sS0FBSyxHQUFHLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLENBQUM7UUFFakMsSUFBSSxDQUFDLEtBQUs7WUFBRSxPQUFPLElBQUksQ0FBQztRQUV4QixJQUFJLENBQUMsTUFBTSxDQUFDLE9BQU8sRUFBRSxxQkFBcUIsS0FBSyxDQUFDLENBQUMsQ0FBQyxZQUFZLEdBQUcsRUFBRSxDQUFDLENBQUM7UUFFckUsT0FBTyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsUUFBUSxDQUFDO0lBQzNCLENBQUM7SUFFRDs7O09BR0c7SUFDSCxvQkFBb0I7UUFDbEIsT0FBTyxDQUFDLEdBQUcsRUFBRSxHQUFHLEVBQUUsSUFBSSxFQUFFLEVBQUU7WUFDeEIsTUFBTSxPQUFPLEdBQUcsSUFBSSxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsR0FBRyxJQUFJLEdBQUcsQ0FBQyxDQUFDO1lBRWhELElBQUksT0FBTyxFQUFFLENBQUM7Z0JBQ1osT0FBTyxDQUFDLEdBQUcsRUFBRSxHQUFHLEVBQUUsSUFBSSxDQUFDLENBQUM7Z0JBRXhCLE9BQU87WUFDVCxDQUFDO1lBRUQsSUFBSSxFQUFFLEVBQUUsQ0FBQztRQUNYLENBQUMsQ0FBQztJQUNKLENBQUM7SUFFRCxnQkFBZ0I7UUFDZCxPQUFPLElBQUEsd0JBQVksRUFBQyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsRUFBRSxHQUFHLENBQUMsRUFBRSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLEtBQUssSUFBSSxDQUFDLENBQUM7SUFDdkYsQ0FBQztJQUVELDhGQUE4RjtJQUM5RixXQUFXO1FBQ1QsSUFBSSxJQUFJLENBQUMsUUFBUSxDQUFDLElBQUksS0FBSyxDQUFDO1lBQUUsT0FBTyxJQUFJLENBQUM7UUFFMUMsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUFoRUQsaUNBZ0VDIn0=

package/dist/types.d.ts

@@ -151,6 +151,47 @@ export type WorkflowExecutorEmbedOptions = Omit<WorkflowExecutorTuningOptions, '
      */
     encryptionKey?: string;
 };
+/**
+ * Options of an embedded BFF. Everything the BFF shares with the agent — the secrets, the Forest
+ * urls, the logger — is inherited rather than repeated: a divergent `authSecret` would make the
+ * agent reject the very tokens the BFF mints, as an opaque 401.
+ */
+export type BffEmbedOptions = {
+    /**
+     * Base64-encoded 32-byte AES-256 key encrypting stored refresh tokens. Gates the OAuth
+     * login/refresh flow (mode 1) and, with it, the AI relay.
+     *
+     * It is not an access control. The data routes accept a `bff_access` bearer whether or not this
+     * is set, because that token is verified against the agent's `authSecret` alone. Omitting it
+     * closes the login flow, not the session-bearer path — what protects that path is `authSecret`.
+     */
+    tokenEncryptionKey?: string;
+    /**
+     * Exact origins (scheme + host + port) allowed to call the BFF from a browser. No wildcard.
+     * Empty means no cross-origin browser access at all, which for a backend-for-frontend is
+     * almost always a mistake — the BFF warns about it at startup.
+     */
+    allowedOrigins?: string[];
+    /** Fallback IANA timezone for a request that carries none. */
+    defaultTimezone?: string;
+    /**
+     * How long a call to the agent may take. Defaults to 10s.
+     *
+     * It bounds how long the BFF waits, and cancels nothing: an action or a write cut off at the
+     * deadline keeps running inside the agent and still commits, so a client retrying on the timeout
+     * can double the mutation. Raise it rather than relying on a retry for operations that are not
+     * idempotent.
+     */
+    agentTimeoutMs?: number;
+    /** How long the AI relay waits for the Forest server. Defaults to 120s. */
+    aiTimeoutMs?: number;
+    /**
+     * Serve `/bff/docs` and `/bff/agent/openapi.json`. Defaults to `false` when embedded: the
+     * document is not filtered per caller, so any authenticated caller reads the name of every
+     * exposed collection, relation and field.
+     */
+    openapiEnabled?: boolean;
+};
 export type AuditTrailRuntime = AuditTrailConfig & {
     store: AuditStore;
     close: () => Promise<void>;
@@ -159,7 +200,12 @@ export type AgentOptionsWithDefaults = Readonly<Required<Omit<AgentOptions, 'aud
     auditTrail: AuditTrailRuntime | null;
 }>;
 export type HttpCallback = (req: IncomingMessage, res: ServerResponse, next?: () => void) => void;
-export type McpRouteMatcher = (url: string) => boolean;
+export type RouteMatcher = (url: string) => boolean;
+/** A handler served at the root of the host application, with the urls it claims. */
+export type RootHandler = {
+    callback: HttpCallback;
+    matches: RouteMatcher;
+};
 export declare enum HttpCode {
     BadRequest = 400,
     Unauthorized = 401,

package/dist/types.js

@@ -22,4 +22,4 @@ var RouteType;
     RouteType[RouteType["Authentication"] = 3] = "Authentication";
     RouteType[RouteType["PrivateRoute"] = 4] = "PrivateRoute";
 })(RouteType || (exports.RouteType = RouteType = {}));
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBc0tBLElBQVksUUFVWDtBQVZELFdBQVksUUFBUTtJQUNsQixxREFBZ0IsQ0FBQTtJQUNoQix5REFBa0IsQ0FBQTtJQUNsQixtREFBZSxDQUFBO0lBQ2YsaURBQWMsQ0FBQTtJQUNkLDJEQUFtQixDQUFBO0lBQ25CLCtEQUFxQixDQUFBO0lBQ3JCLHVFQUF5QixDQUFBO0lBQ3pCLG1EQUFlLENBQUE7SUFDZixxQ0FBUSxDQUFBO0FBQ1YsQ0FBQyxFQVZXLFFBQVEsd0JBQVIsUUFBUSxRQVVuQjtBQUVELElBQVksU0FPWDtBQVBELFdBQVksU0FBUztJQUNuQixpR0FBaUc7SUFDakcsMkRBQWlCLENBQUE7SUFDakIseURBQWdCLENBQUE7SUFDaEIsdURBQWUsQ0FBQTtJQUNmLDZEQUFrQixDQUFBO0lBQ2xCLHlEQUFnQixDQUFBO0FBQ2xCLENBQUMsRUFQVyxTQUFTLHlCQUFULFNBQVMsUUFPcEIifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBbU5BLElBQVksUUFVWDtBQVZELFdBQVksUUFBUTtJQUNsQixxREFBZ0IsQ0FBQTtJQUNoQix5REFBa0IsQ0FBQTtJQUNsQixtREFBZSxDQUFBO0lBQ2YsaURBQWMsQ0FBQTtJQUNkLDJEQUFtQixDQUFBO0lBQ25CLCtEQUFxQixDQUFBO0lBQ3JCLHVFQUF5QixDQUFBO0lBQ3pCLG1EQUFlLENBQUE7SUFDZixxQ0FBUSxDQUFBO0FBQ1YsQ0FBQyxFQVZXLFFBQVEsd0JBQVIsUUFBUSxRQVVuQjtBQUVELElBQVksU0FPWDtBQVBELFdBQVksU0FBUztJQUNuQixpR0FBaUc7SUFDakcsMkRBQWlCLENBQUE7SUFDakIseURBQWdCLENBQUE7SUFDaEIsdURBQWUsQ0FBQTtJQUNmLDZEQUFrQixDQUFBO0lBQ2xCLHlEQUFnQixDQUFBO0FBQ2xCLENBQUMsRUFQVyxTQUFTLHlCQUFULFNBQVMsUUFPcEIifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestadmin/agent",
-  "version": "1.99.2",
+  "version": "1.100.1",
   "main": "dist/index.js",
   "license": "GPL-3.0",
   "publishConfig": {
@@ -49,35 +49,42 @@
   },
   "devDependencies": {
     "@fastify/express": "^1.1.0",
+    "@forestadmin/agent-bff": "1.29.0",
     "@forestadmin/datasource-sql": "1.17.14",
-    "@forestadmin/workflow-executor": "1.28.0",
+    "@forestadmin/workflow-executor": "1.28.1",
     "@nestjs/common": "^11.1.24",
     "@nestjs/core": "^11.1.24",
     "@nestjs/platform-express": "^11.1.24",
     "@nestjs/platform-fastify": "^11.1.24",
     "@shopify/jest-koa-mocks": "^3.1.0",
-    "sqlite3": "^5.1.7",
     "@types/json-api-serializer": "^2.6.3",
     "@types/jsonwebtoken": "^9.0.1",
     "@types/koa": "^2.13.5",
     "@types/koa__cors": "^3.3.0",
     "@types/superagent": "^8.1.9",
+    "@types/supertest": "^6.0.2",
     "express": "^4.18.2",
     "fastify": "^3.29.0",
     "fastify2": "npm:fastify@^2.15.3",
     "fastify4": "npm:fastify@^4.28.0",
     "openid-client": "^5.7.1",
     "reflect-metadata": "^0.1.13",
-    "rxjs": "^7.8.0"
+    "rxjs": "^7.8.0",
+    "sqlite3": "^5.1.7",
+    "supertest": "^7.1.3"
   },
   "peerDependencies": {
     "@fastify/express": "^1.1.0 || ^2.0.0 || ^3.0.0 || ^4.0.0",
-    "@forestadmin/workflow-executor": "1.28.0"
+    "@forestadmin/agent-bff": "1.29.0",
+    "@forestadmin/workflow-executor": "1.28.1"
   },
   "peerDependenciesMeta": {
     "@fastify/express": {
       "optional": true
     },
+    "@forestadmin/agent-bff": {
+      "optional": true
+    },
     "@forestadmin/workflow-executor": {
       "optional": true
     }