@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/UAGProjectInterface.js

@@ -1,21 +1,36 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UAGProjectInterface = void 0;
 const appserver_1 = require("@formio/appserver");
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const formflow_1 = require("./formflow");
+const runner_1 = require("./runner");
 const express_1 = require("express");
-const tools_1 = require("./tools");
 const router_1 = require("./router");
 const template_1 = require("./template");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const version_1 = require("./version");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const router_2 = require("./agent/router");
+const readers_1 = require("./documents/readers");
+const tools_1 = require("./agent/tools");
 const debug = require('debug')('formio:uag:UAGProjectInterface');
 class UAGProjectInterface extends appserver_1.ProjectInterface {
+    /** The names of the UAG forms the project currently has. */
+    get formNames() {
+        return Object.values(this.forms).map((form) => form.uag?.name).filter(Boolean);
+    }
     get config() { return appserver_1.ProjectInterface.module?.config || {}; }
     constructor(endpoint) {
         super(endpoint);
         this.user = null;
-        this.formNames = [];
         this.uagTemplate = null;
-        this.mcpServer = new mcp_js_1.McpServer({ name: 'formio-uag', version: '1.0.0' });
+        /** Engines enabled at startup; empty until UAGServer.router() resolves them. */
+        this.engines = new formflow_1.EngineRegistry();
+        this.mcpServer = new mcp_js_1.McpServer({ name: 'formio-uag', version: version_1.UAG_VERSION });
     }
     async initialize() {
         await super.initialize();
@@ -24,27 +39,40 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
     }
     // Build a fresh McpServer with all tools registered. A new instance is created
     // per request so concurrent requests never share (and overwrite) a transport.
-    async buildMcpServer() {
-        const server = new mcp_js_1.McpServer({ name: 'formio-uag', version: '1.0.0' });
-        // Get the standard UAG tools.
-        const tools = await (0, tools_1.getTools)(this);
-        // Add the custom tools from config.
-        if (this.config?.tools?.length) {
-            tools.push(...this.config.tools);
+    // A scoped token narrows the tools to its own list, and only ever to tools
+    // annotated read-only: no model may write through /mcp with one.
+    async buildMcpServer(scope) {
+        const server = new mcp_js_1.McpServer({ name: 'formio-uag', version: version_1.UAG_VERSION });
+        // The standard UAG tools, plus the custom tools from config.
+        let tools = await (0, tools_1.allTools)(this);
+        if (scope) {
+            tools = (0, formflow_1.toolsForScope)(tools, scope).filter((tool) => tool.annotations?.readOnlyHint === true);
         }
-        // Iterate and register all the tools.
+        // Register all the tools (allTools() keeps only the named ones).
         for (const tool of tools) {
-            if (tool?.name) {
-                server.registerTool(tool.name, {
-                    title: tool.title,
-                    description: tool.description,
-                    inputSchema: tool.inputSchema,
-                    // Carries readOnly/destructive/idempotent/openWorld through to the
-                    // client. Tools from config.tools may omit them, so this stays
-                    // conditional rather than sending `annotations: undefined`.
-                    ...(tool.annotations && { annotations: tool.annotations })
-                }, tool.execute);
-            }
+            server.registerTool(tool.name, {
+                title: tool.title,
+                description: tool.description,
+                // Always a schema, even an empty one: the MCP SDK calls a tool
+                // registered without one as `execute(extra)`, and every tool is
+                // `execute(args, extra)`, as Agent API research calls it.
+                inputSchema: tool.inputSchema || {},
+                // Carries readOnly/destructive/idempotent/openWorld through to the
+                // client. Tools from config.tools may omit them, so this stays
+                // conditional rather than sending `annotations: undefined`.
+                ...(tool.annotations && { annotations: tool.annotations })
+            }, (args, extra) => (0, tools_1.runTool)(tool, this, args, extra));
+        }
+        // A scoped token that allows no tools must still answer tools/list, with
+        // an empty list: clients list tools first,
+        // and a server with nothing registered would not offer tools at all.
+        if (!tools.length) {
+            server.server.registerCapabilities({ tools: {} });
+            server.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: [] }));
+            server.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => ({
+                content: [{ type: 'text', text: `The tool "${request.params.name}" is not available to this token.` }],
+                isError: true
+            }));
         }
         return server;
     }
@@ -52,32 +80,92 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
         const formInterface = super.addForm(form, machineName);
         if (!formInterface)
             return;
-        machineName = formInterface?.form?.machineName;
-        if (form.tags?.includes('uag')) {
-            debug(`Registering UAG form: ${machineName}`);
-            formInterface.uag = {
-                machineName: machineName,
-                name: form.name || form.path || machineName,
-                title: form.title || form.name || machineName,
-                description: form.properties?.description || `A form to submit new ${form.title} records.`
-            };
-            this.formNames.push(formInterface.uag.name);
+        // The registration itself is derived from the form by UAGFormInterface.setForm().
+        if (formInterface.uag) {
+            debug(`Registering UAG form: ${formInterface.uag.machineName}`);
         }
         return formInterface;
     }
-    uagRouter() {
+    /**
+     * The UAG's routes: `/mcp`, and unless excluded, `/agent/capabilities`.
+     * UAGServer mounts capabilities separately, ahead of the project router. A
+     * form's agent operations are on the form's own routes (UAGFormInterface).
+     */
+    uagRouter(includeAgentApi = true) {
         const router = (0, express_1.Router)();
         const uagRouter = (0, router_1.UAGRouter)(this);
         router.use('/mcp', (req, res, next) => this.authorizeRequest(req, res, next), uagRouter);
+        if (includeAgentApi) {
+            router.use(this.agentRouter());
+        }
         return router;
     }
+    /** `/agent/capabilities`, behind its own authentication. */
+    agentRouter() {
+        return (0, router_2.AgentRouter)(this, (0, formflow_1.formflowAuthenticate)(this));
+    }
+    /** Whether runs after the save are recorded and survive a restart (the UAG's database). */
+    durableRuns() {
+        return (0, runner_1.taskRunner)(this).durable;
+    }
+    /** The engines enabled for Agentic Formflow. */
+    formflowEngines() {
+        return this.engines;
+    }
+    /**
+     * Agentic Formflow's routing, Agent API and auth settings. The engine
+     * settings stay here: the UAG loads the engines, not core.
+     */
+    formflowConfig() {
+        const { engines, engineTypes, ...config } = this.config || {};
+        return config;
+    }
+    /** A form tagged "uag", or null. */
+    async formflowForm(name) {
+        const form = await this.getForm(name);
+        return form?.uag ? form : null;
+    }
+    /**
+     * Readers for uploaded documents: one built from the installed converters,
+     * which reads every type with a route to text.
+     */
+    formflowFileReaders() {
+        return this.plugins ? [(0, readers_1.converterFileReader)(this.plugins)] : [];
+    }
+    /** Every MCP tool, as Agentic Formflow tools. */
+    async formflowTools() {
+        return (await (0, tools_1.allTools)(this)).map((tool) => (0, tools_1.formflowTool)(tool, this));
+    }
     async authorizeRequest(req, res, next) {
         try {
+            let authorization = req.get('authorization');
+            // A scoped token carries the identity it was issued for (the caller's
+            // own token, or admin) and limits the tools /mcp offers.
+            const bearer = (0, formflow_1.bearerOf)(authorization);
+            const scoped = bearer ? (0, formflow_1.readScopedToken)(this, bearer) : null;
+            if (scoped) {
+                req.uagScope = scoped;
+                if (scoped.admin) {
+                    req.auth = new appserver_1.AuthRequest(this, true);
+                    return next();
+                }
+                if (!scoped.bearer) {
+                    throw new Error('Scoped token has no identity');
+                }
+                authorization = `Bearer ${scoped.bearer}`;
+            }
             const pkce = this.provider('auth.pkce');
             if (!pkce) {
                 throw new Error('No PKCE provider configured');
             }
-            const auth = await pkce?.authorize(req.get('authorization'));
+            // A scoped token may carry a Form.io user token (the caller's x-jwt-token,
+            // or one the UAG signed for a run's research), not one of /mcp's own
+            // access tokens: it is verified as the project verifies x-jwt-token.
+            if (scoped?.bearer && !jsonwebtoken_1.default.decode(scoped.bearer)?.sub) {
+                req.auth = await this.formioTokenAuth(pkce, scoped.bearer);
+                return next();
+            }
+            const auth = await pkce.authorize(authorization);
             if (!auth || !auth.user) {
                 throw new Error('Unauthorized');
             }
@@ -85,13 +173,76 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
             next();
         }
         catch (err) {
+            // Point MCP clients at OAuth sign-in only when it is on (MCP_OAUTH, with the database).
+            const pkce = this.provider('auth.pkce');
+            const metadata = pkce?.oauthReady ? `, resource_metadata="${pkce.publicUrl(req)}/.well-known/oauth-protected-resource"` : '';
+            // RFC 6750 3.1: a request that presented a token is told it is invalid; one
+            // that presented none gets no error code, only the challenge.
+            const presented = !!(0, formflow_1.bearerOf)(req.get('authorization'));
+            const description = String(err?.message || err || 'Unauthorized').replace(/["\\]/g, '');
+            const challenge = presented ? `, error="invalid_token", error_description="${description}"` : '';
             return res.status(401).set({
-                'WWW-Authenticate': `Bearer realm="uag-server", resource_metadata="${this.config?.baseUrl}/.well-known/oauth-protected-resource"`
+                'WWW-Authenticate': `Bearer realm="uag-server"${challenge}${metadata}`
             }).json({
-                detail: err.message || err
+                error: presented ? 'invalid_token' : 'unauthorized',
+                error_description: presented ? description : 'Send an access token: Authorization: Bearer <token>.'
             });
         }
     }
+    /**
+     * The user a Form.io token stands for, as the project's x-jwt-token
+     * authentication decides it: a token tied to a Form.io session is asked of
+     * Form.io; one signed with this UAG's secret is read from its claims, bound
+     * to this project; any other is asked of Form.io. Never an administrator:
+     * an administrator's research carries no user token.
+     */
+    async formioTokenAuth(provider, token) {
+        const auth = new appserver_1.AuthRequest(this);
+        const projectId = String(this.project?._id || '');
+        const fromFormio = async () => {
+            const user = await provider.formioUser(token);
+            if (!user)
+                throw new Error('Unauthorized');
+            // A user of another project is refused, as /mcp's own sign-in refuses one.
+            if (user.project && String(user.project) !== projectId)
+                throw new Error('Forbidden');
+            return auth.fromFormioUser(user, token, this);
+        };
+        if (this.proxyMode && appserver_1.AuthProvider.sessionToken(token)) {
+            await fromFormio();
+        }
+        else {
+            const secret = this.config?.auth?.secret;
+            let verified = null;
+            try {
+                if (secret)
+                    verified = jsonwebtoken_1.default.verify(token, secret);
+            }
+            catch (err) {
+                if (err?.name === 'TokenExpiredError')
+                    throw new Error('Token Expired');
+            }
+            if (verified) {
+                // Only a token for this project: one naming no project (or another) is refused.
+                if (!projectId || String(verified.project?._id || '') !== projectId)
+                    throw new Error('Forbidden');
+                // Kept as it is, never signed again: a token the UAG signed for a run
+                // keeps its roles and its short lifetime when forwarded to Form.io.
+                auth.token = token;
+                await auth.fromAuthToken(verified, this);
+            }
+            else if (this.proxyMode) {
+                await fromFormio();
+            }
+            else {
+                throw new Error('Unauthorized');
+            }
+        }
+        if (!auth.user)
+            throw new Error('Unauthorized');
+        auth.admin = false;
+        return auth;
+    }
     mcpJSONResponse(data = {}, isError = false) {
         return {
             content: [

package/lib/actionLogs.d.ts

@@ -0,0 +1,24 @@
+import { Router } from 'express';
+import type { TaskRunRecord } from './runs';
+import type { UAGProjectInterface } from './UAGProjectInterface';
+/** A run record as a Form.io action item. */
+export declare function actionItem(record: TaskRunRecord): {
+    _id: string;
+    title: string;
+    action: string;
+    project: string;
+    form: string;
+    submission?: string | undefined;
+    handler: "after" | "before";
+    method: string;
+    state: string;
+    messages: {
+        datetime: string;
+        info: string;
+        data: any;
+    }[];
+    data: any;
+    created: string;
+    modified: string;
+};
+export declare function ActionLogRouter(project: UAGProjectInterface): Router;

package/lib/actionLogs.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actionItem = actionItem;
+exports.ActionLogRouter = ActionLogRouter;
+const appserver_1 = require("@formio/appserver");
+const express_1 = require("express");
+const lodash_1 = require("lodash");
+const runner_1 = require("./runner");
+const debug = require('debug')('formio:uag:actionLogs');
+/**
+ * Action Logs in a portal stage connected to the UAG. The portal asks the
+ * stage's URL for `/action` (Form.io Enterprise's action items). The UAG asks
+ * Form.io with the caller's own credential, so Form.io decides who may see the
+ * logs, and adds its Run task records to Form.io's entries, newest first.
+ *
+ * Without the UAG's database there are no records, and these requests pass
+ * through to Form.io unchanged.
+ */
+const STATES = { pending: 'new', running: 'inprogress', done: 'complete', failed: 'error' };
+const STATUSES = { new: 'pending', inprogress: 'running', complete: 'done', error: 'failed' };
+const MAX_PAGE = 1000;
+/** The caller's credential, as sent, for Form.io. */
+function credential(req) {
+    return Object.fromEntries(Object.entries(req.headers)
+        .filter(([name, value]) => appserver_1.Actions.CREDENTIAL_HEADERS.includes(name.toLowerCase()) && typeof value === 'string'));
+}
+/** A run record as a Form.io action item. */
+function actionItem(record) {
+    const messages = [
+        { datetime: record.created.toISOString(), info: `Run task "${record.task}" ${record.durable ? 'queued' : 'started'} (${record.answer === 'decisions' ? 'decision fields only' : 'the whole task'}).`, data: {} }
+    ];
+    if (record.started) {
+        messages.push({ datetime: record.started.toISOString(), info: `Started (attempt ${record.attempts}).`, data: {} });
+    }
+    if (record.finished) {
+        const written = record.written || [];
+        const cleared = record.cleared || [];
+        const refused = record.refused || [];
+        const left = refused.length ? ` Left out answers the form refused: ${refused.join(', ')}.` : '';
+        const info = (record.status === 'failed'
+            ? `Failed: ${record.error || 'unknown error'}`
+            : record.saved
+                ? `Saved ${written.length} field(s)${written.length ? `: ${written.join(', ')}` : ''}${cleared.length ? `; cleared ${cleared.join(', ')}` : ''}.`
+                : 'Nothing changed, so nothing was saved.') + left;
+        messages.push({ datetime: record.finished.toISOString(), info, data: { engines: record.engines || [], written, cleared, ...(refused.length && { refused }) } });
+    }
+    return {
+        _id: String(record._id),
+        title: record.action,
+        action: 'agentRunTask',
+        project: record.project,
+        form: record.form,
+        ...(record.submission && { submission: record.submission }),
+        handler: record.handler,
+        method: record.method,
+        state: STATES[record.status],
+        messages,
+        data: {
+            task: record.task,
+            answer: record.answer,
+            durable: record.durable,
+            ...(record.actingFor?._id && { actingFor: { _id: record.actingFor._id, ...(record.actingFor.email && { email: record.actingFor.email }) } }),
+            ...(record.agentRole && { agentRole: record.agentRole })
+        },
+        created: record.created.toISOString(),
+        modified: record.modified.toISOString()
+    };
+}
+/** The records filter for the portal's query (`form`, `submission`, `handler`, `method`, `state`, `title__regex`). */
+function filterOf(project, query) {
+    const filter = { project: String(project.project?._id || '') };
+    for (const field of ['form', 'submission', 'handler', 'method']) {
+        if (typeof query[field] === 'string' && query[field])
+            filter[field] = query[field];
+    }
+    if (typeof query.state === 'string' && query.state)
+        filter.status = STATUSES[query.state] || '__none__';
+    // Matched as text: a portal filter is never run as a regular expression against the database.
+    if (typeof query.title__regex === 'string' && query.title__regex)
+        filter.action = { $regex: (0, lodash_1.escapeRegExp)(query.title__regex), $options: 'i' };
+    return filter;
+}
+const number = (value, fallback) => {
+    const parsed = parseInt(String(value ?? ''), 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+};
+function ActionLogRouter(project) {
+    const router = (0, express_1.Router)();
+    /** Ask Form.io, as the caller, for its action items. */
+    const ask = (req, path, query) => fetch(`${project.endpoint}${path}${query.toString() ? `?${query}` : ''}`, { headers: { ...credential(req), Accept: 'application/json' } });
+    /** Relay Form.io's answer as it is. */
+    const relay = async (res, response) => {
+        const range = response.headers.get('content-range');
+        if (range)
+            res.set('Content-Range', range);
+        res.status(response.status).type(response.headers.get('content-type') || 'application/json').send(await response.text());
+    };
+    router.get('/action', async (req, res, next) => {
+        const records = (0, runner_1.taskRunner)(project).records;
+        if (!records || !project.endpoint)
+            return next();
+        try {
+            const skip = number(req.query.skip, 0);
+            // A limit of 0 is the default page, not every record.
+            const limit = Math.min(number(req.query.limit, 10) || 10, MAX_PAGE);
+            // Both lists are sorted the same way, so the page is among the first skip + limit of each.
+            const query = new URLSearchParams(Object.entries(req.query).filter(([, value]) => typeof value === 'string'));
+            query.set('skip', '0');
+            query.set('limit', String(Math.min(skip + limit, MAX_PAGE)));
+            query.set('sort', '-modified');
+            const response = await ask(req, '/action', query);
+            if (!response.ok)
+                return relay(res, response);
+            const formio = await response.json();
+            const formioTotal = Number((response.headers.get('content-range') || '').split('/')[1]) || formio.length;
+            const own = await records.list(filterOf(project, req.query), Math.min(skip + limit, MAX_PAGE));
+            const merged = [...formio, ...own.items.map(actionItem)]
+                .sort((a, b) => Date.parse(b.modified || b.created) - Date.parse(a.modified || a.created));
+            const page = merged.slice(skip, skip + limit);
+            const total = formioTotal + own.total;
+            res.set('Content-Range', page.length ? `${skip}-${skip + page.length - 1}/${total}` : `*/${total}`);
+            res.json(page);
+        }
+        catch (err) {
+            debug(`Action Logs failed: ${err?.message || err}`);
+            next(err);
+        }
+    });
+    router.get('/action/:id', async (req, res, next) => {
+        const records = (0, runner_1.taskRunner)(project).records;
+        if (!records || !project.endpoint)
+            return next();
+        try {
+            const record = await records.get(String(req.params.id));
+            if (!record || record.project !== String(project.project?._id || '')) {
+                return relay(res, await ask(req, `/action/${encodeURIComponent(String(req.params.id))}`, new URLSearchParams()));
+            }
+            // Form.io decides who may read Action Logs.
+            const allowed = await ask(req, '/action', new URLSearchParams({ limit: '1' }));
+            if (!allowed.ok)
+                return relay(res, allowed);
+            res.json(actionItem(record));
+        }
+        catch (err) {
+            next(err);
+        }
+    });
+    return router;
+}

package/lib/actions/runTask.d.ts

@@ -0,0 +1,43 @@
+import { Action, FormInterface, SubmissionRequest, SubmissionResponse } from '@formio/appserver';
+import { NextFunction } from 'express';
+export declare const RUN_TASK = "agentRunTask";
+/**
+ * Remove, from what a client sends, the values of the fields each of the form's
+ * Run task actions owns and marks `uagAuthoritative`: on an update they keep
+ * their stored values; on a create they start empty. This covers every Run
+ * task action on the form, whatever its method, conditions or when it runs, so
+ * a client can never store a value the server decides: not before the task
+ * runs, and not through a method the task does not run on. The runner's own
+ * save is not a client's, and is left alone.
+ *
+ * As `before:submission:<op>` hooks, these run after an update has loaded the
+ * stored submission and before the request's data replaces it.
+ */
+export declare function ownedFieldHooks(): {
+    'before:submission:create': (form: FormInterface) => Promise<FormInterface | ((req: SubmissionRequest, res: SubmissionResponse, next: NextFunction) => Promise<void>)>;
+    'before:submission:update': (form: FormInterface) => Promise<FormInterface | ((req: SubmissionRequest, res: SubmissionResponse, next: NextFunction) => Promise<void>)>;
+};
+/**
+ * Decide how a submission is created through the UAG, from the form's
+ * submission access and its Run task actions that run on create:
+ * - a caller whose roles may create submissions creates it with their own token;
+ * - otherwise, when an action names an agent role the form grants "Create All",
+ *   and the caller has one of the actions' submitter roles, the agent creates it
+ *   on their behalf, owned by them;
+ * - otherwise the create is refused.
+ * Run as a `before:access:create` hook, before the caller's access is checked.
+ */
+export declare function onBehalfHook(): (form: FormInterface) => Promise<FormInterface | ((req: SubmissionRequest, res: SubmissionResponse, next: NextFunction) => Promise<void | SubmissionResponse>)>;
+/** The hooks Run task needs: owned fields kept from clients, and creation on a user's behalf. */
+export declare function runTaskHooks(): {
+    'before:submission:create': (form: FormInterface) => Promise<FormInterface | ((req: SubmissionRequest, res: SubmissionResponse, next: NextFunction) => Promise<void>)>;
+    'before:submission:update': (form: FormInterface) => Promise<FormInterface | ((req: SubmissionRequest, res: SubmissionResponse, next: NextFunction) => Promise<void>)>;
+    'before:access:create': (form: FormInterface) => Promise<FormInterface | ((req: SubmissionRequest, res: SubmissionResponse, next: NextFunction) => Promise<void | SubmissionResponse>)>;
+};
+/**
+ * "Agent: Run task": run one of the form's tasks on a submission sent to the
+ * UAG, before the save (the submitter waits, and Form.io stores the result as
+ * the one save) or after it, in the background (the results are saved as an
+ * update, which runs the form's update actions in turn).
+ */
+export declare const RunTaskAction: Action;