@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/documents/routes.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConverterRoutes = exports.stepName = void 0;
+const mime_1 = require("./mime");
+const detect_1 = require("./detect");
+/** A converter as `name@version`, as results record routes. */
+const stepName = (converter) => `${converter.name}@${converter.version}`;
+exports.stepName = stepName;
+/**
+ * Routes from source types to representations over a set of converters.
+ * When several converters can do a step, the component's pin wins, then the
+ * operator's `documents.prefer`, then the highest rank, then the name.
+ */
+class ConverterRoutes {
+    constructor(converters, prefer = {}) {
+        this.converters = converters;
+        this.prefer = prefer;
+    }
+    /** The converter for one step from `source` to `target`, or undefined when none can do it. */
+    choose(source, target, pins = {}) {
+        const candidates = this.converters.filter((converter) => converter.produces.includes(target) && converter.accepts.some((accept) => accept.type === source));
+        if (!candidates.length)
+            return undefined;
+        for (const preferred of [pins[source], this.prefer[source]]) {
+            const found = preferred && candidates.find((converter) => converter.name === preferred);
+            if (found)
+                return found;
+        }
+        return [...candidates].sort((a, b) => ((b.rank || 0) - (a.rank || 0)) || a.name.localeCompare(b.name))[0];
+    }
+    /** The steps from `source` to a PDF: [] for a PDF, one converter otherwise, or null. */
+    toPdf(source, pins = {}) {
+        if (source === mime_1.MIME.pdf)
+            return [];
+        const converter = this.choose(source, 'pdf', pins);
+        return converter ? [converter] : null;
+    }
+    /** The steps from `source` to text: one converter, or to a PDF and then its text; null when none. */
+    toText(source, pins = {}) {
+        const direct = this.choose(source, 'text', pins);
+        if (direct)
+            return [direct];
+        const pdf = this.toPdf(source, pins);
+        const fromPdf = pdf && this.choose(mime_1.MIME.pdf, 'text', pins);
+        return pdf && fromPdf ? [...pdf, fromPdf] : null;
+    }
+    /**
+     * The first of a plugin's input sets every representation of which the
+     * file can reach. With both PDF and text, the text is always that same
+     * PDF's text, so content made from the PDF is checked against it.
+     */
+    route(source, inputs, pins = {}) {
+        for (const set of inputs) {
+            if (set.includes('pdf')) {
+                const pdf = this.toPdf(source, pins);
+                if (!pdf)
+                    continue;
+                if (!set.includes('text'))
+                    return { inputs: set, pdf };
+                const fromPdf = this.choose(mime_1.MIME.pdf, 'text', pins);
+                if (!fromPdf)
+                    continue;
+                return { inputs: set, pdf, text: [...pdf, fromPdf] };
+            }
+            if (set.includes('text')) {
+                const text = this.toText(source, pins);
+                if (text)
+                    return { inputs: set, text };
+            }
+        }
+        return null;
+    }
+    /** Every source type a converter reads, and PDF. */
+    sourceTypes() {
+        return [...new Set([mime_1.MIME.pdf, ...mime_1.TEXT_TYPES.filter((type) => this.converters.some((c) => c.accepts.some((a) => a.type === type))),
+                ...this.converters.flatMap((converter) => converter.accepts.map((accept) => accept.type))])];
+    }
+    /** The source types a plugin with these inputs can take, with their routes: its manifest's `accept`. */
+    accept(inputs) {
+        const entries = [];
+        for (const type of this.sourceTypes()) {
+            const route = this.route(type, inputs);
+            if (!route)
+                continue;
+            entries.push({
+                type,
+                ext: (0, detect_1.extensionsOf)(type, this.converters),
+                routes: {
+                    inputs: route.inputs,
+                    ...(route.pdf && { pdf: route.pdf.map((c) => c.name) }),
+                    ...(route.text && { text: route.text.map((c) => c.name) })
+                },
+                converters: this.converters.filter((c) => c.accepts.some((a) => a.type === type)).map((c) => c.name)
+            });
+        }
+        return entries;
+    }
+}
+exports.ConverterRoutes = ConverterRoutes;

package/lib/documents/types.d.ts

@@ -0,0 +1,126 @@
+import type { Plugin, PluginContext } from '@formio/appserver';
+import type { GenerateRequest, GenerateResponse } from '@formio/uag-sdk';
+export type Representation = 'pdf' | 'text';
+export type TextFormat = 'plain' | 'markdown' | 'csv';
+/** Plugin type `converter` (apiVersion 1, experimental): a file into a PDF or text. */
+export interface Converter extends Plugin {
+    type: 'converter';
+    /** MIME types (canonical) and extensions it reads. */
+    accepts: Array<{
+        type: string;
+        ext?: string[];
+    }>;
+    produces: Representation[];
+    /** Default 0; the higher wins when several converters can do a step. */
+    rank?: number;
+    /** A canonical type for formats the shared detection does not know, or null. */
+    detect?(head: Buffer, hint: {
+        name: string;
+        type: string;
+    }): string | null;
+    /** Defaults: 25 MB, 120000 ms, 2 at a time. */
+    limits?: {
+        maxBytes?: number;
+        timeoutMs?: number;
+        concurrency?: number;
+    };
+    convert(input: {
+        buffer: Buffer;
+        type: string;
+        name: string;
+    }, options: {
+        to: Representation;
+        settings: Record<string, any>;
+        signal: AbortSignal;
+        tmpdir: string;
+        log: PluginContext['log'];
+    }): Promise<ConverterOutput>;
+}
+export type ConverterOutput = {
+    pdf: Buffer;
+    pages?: number;
+    warnings?: string[];
+} | {
+    text: string;
+    textFormat: TextFormat;
+    pages?: Array<{
+        page: number;
+        text: string;
+    }>;
+    warnings?: string[];
+};
+export type DocumentFile = {
+    name: string;
+    type: string;
+    size: number;
+    sha256: string;
+    document: {
+        pdf?: Buffer;
+        pages?: number;
+        text?: string;
+        textFormat?: string;
+        textPages?: Array<{
+            page: number;
+            text: string;
+        }>;
+    };
+    /** The converters it went through, as name@version. */
+    route: string[];
+    original(): Promise<Buffer>;
+};
+export type DocumentContext = {
+    files: DocumentFile[];
+    /** Markdown. */
+    instructions: string;
+    /** This component's plugin settings, defaults applied. */
+    settings: Record<string, any>;
+    /** Operator settings. */
+    config: Record<string, any>;
+    form: {
+        id: string;
+        path: string;
+        title: string;
+    };
+    component: {
+        key: string;
+        path: string;
+        label: string;
+    };
+    /** Submission data sent with the request: context only, untrusted. */
+    data: Record<string, any>;
+    agent: {
+        generate(request: Omit<GenerateRequest, 'signal'>): Promise<GenerateResponse>;
+    };
+    progress(fraction: number, message?: string): void;
+    signal: AbortSignal;
+    log: PluginContext['log'];
+};
+export type Issue = {
+    kind: string;
+    message: string;
+    output?: string;
+    document?: string;
+    page?: number;
+    file?: string;
+};
+export type DocumentResult = {
+    content: string;
+    status: 'ok' | 'flagged';
+    issues?: Issue[];
+    summary?: string;
+};
+/** Plugin type `document` (apiVersion 1, experimental): files and instructions into content. */
+export interface DocumentPlugin extends Plugin {
+    type: 'document';
+    /** Acceptable representation sets, in order of preference. */
+    inputs: Representation[][];
+    /** JSON only; keys are relative to the plugin's settings object. */
+    editForm?: any[];
+    defaults?: Record<string, any>;
+    /** May people edit the content? Default false. */
+    editable?: boolean;
+    /** Default 'markdown'. */
+    output?: 'markdown' | 'text';
+    validateSettings?(settings: Record<string, any>): string[];
+    process(ctx: DocumentContext): Promise<DocumentResult>;
+}

package/lib/documents/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/documents/uagJs.d.ts

@@ -0,0 +1,17 @@
+import { Router } from 'express';
+import type { PluginRegistry, ServedComponent } from '@formio/appserver';
+/**
+ * `@formio/uag-js` from the UAG's own installation, at stable URLs (never a
+ * version in the path: the portal remembers its one-time prompt by URL):
+ *
+ * - `/uag-js/uag.use.js`: the bundle, registering itself with this UAG's URL and the manifest;
+ * - `/uag-js/portal.js`: the same in portal mode (the component only), then `?chain=` (https only);
+ * - `/uag-js/portal.css`: the stylesheet, after `@import url(<chain>)` when `?chain=` is given;
+ * - `/uag-js/uag-js.css`: the stylesheet.
+ *
+ * The modules' components come after: each script after the registration in
+ * `uag.use.js` and `portal.js`, each stylesheet after `uag-js.css` (and in
+ * `portal.css`), and each on its own at `/uag-js/components/<type>.js|css`.
+ * They are read on every request, as the bundle is, so the ETag follows them.
+ */
+export declare function uagJsRouter(registry: () => PluginRegistry | undefined, components?: () => ServedComponent[]): Router;

package/lib/documents/uagJs.js

@@ -0,0 +1,157 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uagJsRouter = uagJsRouter;
+const fs_1 = __importDefault(require("fs"));
+const vm_1 = __importDefault(require("vm"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const express_1 = require("express");
+/** Where @formio/uag-js is installed: as a package, or the UAG's own workspace copy. */
+function uagJsDirectory() {
+    try {
+        return path_1.default.dirname(require.resolve('@formio/uag-js/package.json'));
+    }
+    catch {
+        const local = path_1.default.resolve(__dirname, '..', '..', 'packages', 'uag-js');
+        return fs_1.default.existsSync(path_1.default.join(local, 'index.js')) ? local : undefined;
+    }
+}
+const read = (file) => fs_1.default.readFileSync(path_1.default.join(uagJsDirectory() || '', file), 'utf8');
+/** A chained script or stylesheet URL from `?chain=`, when it is an absolute URL of the allowed schemes. */
+function chainOf(req, schemes) {
+    const chain = typeof req.query.chain === 'string' ? req.query.chain : '';
+    if (!chain)
+        return undefined;
+    try {
+        const url = new URL(chain);
+        return schemes.includes(url.protocol) ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The script that registers the bundle once formio.js is on the page: with
+ * this UAG's URL (from the script's own src) and the manifest, and in portal
+ * mode for the portal script, then loads the chained script over https only.
+ */
+function registration(manifest, options) {
+    return `
+;(function () {
+    var manifest = ${JSON.stringify(manifest).replace(/</g, '\\u003c')};
+    var script = document.currentScript;
+    var src = script && script.src ? new URL(script.src, location.href) : null;
+    var uagUrl = src ? src.href.slice(0, src.href.indexOf('/uag-js/')) : location.origin;
+    function register() {
+        var Formio = window.Formio;
+        var lib = window.FormioUAG;
+        if (!Formio || !lib || typeof Formio.use !== 'function') return false;
+        Formio.use(lib.UAG(uagUrl, { ${options.portal ? 'portal: true, ' : ''}manifest: manifest }));
+        return true;
+    }
+    if (!register()) {
+        var tries = 0;
+        var timer = setInterval(function () { if (register() || ++tries > 600) clearInterval(timer); }, 50);
+    }
+    ${options.chain ? `var chain = document.createElement('script');
+    chain.src = ${JSON.stringify(options.chain)};
+    document.head.appendChild(chain);` : ''}
+})();
+`;
+}
+/** Whether each component script parses as a classic browser script, by its content (checked once per content). */
+const parsed = new Map();
+function parsesAsScript(file, source) {
+    const hash = (0, crypto_1.createHash)('sha256').update(source).digest('base64url');
+    const known = parsed.get(file);
+    if (known?.hash === hash)
+        return known.ok;
+    let ok = true;
+    try {
+        // Compiled only, never run. Wrapped as the bundle wraps it, so the check matches what the browser parses.
+        new vm_1.default.Script(`try {\n${source}\n} catch (err) {}`, { filename: file });
+    }
+    catch {
+        ok = false;
+        console.warn(`[formio-uag] The component script ${file} is not a browser script (an ES module, or a syntax error); it is left out of uag.use.js and portal.js.`);
+    }
+    parsed.set(file, { hash, ok });
+    return ok;
+}
+/** Serve one file: public, revalidated every time (no-cache), with an ETag from its content and the manifest. */
+function serve(req, res, type, body) {
+    const etag = `"${(0, crypto_1.createHash)('sha256').update(body).digest('base64url')}"`;
+    res.set({ 'Content-Type': `${type}; charset=utf-8`, 'Cache-Control': 'no-cache', ETag: etag, 'Access-Control-Allow-Origin': '*' });
+    if (req.headers['if-none-match'] === etag)
+        return res.status(304).end();
+    res.status(200).send(body);
+}
+/**
+ * `@formio/uag-js` from the UAG's own installation, at stable URLs (never a
+ * version in the path: the portal remembers its one-time prompt by URL):
+ *
+ * - `/uag-js/uag.use.js`: the bundle, registering itself with this UAG's URL and the manifest;
+ * - `/uag-js/portal.js`: the same in portal mode (the component only), then `?chain=` (https only);
+ * - `/uag-js/portal.css`: the stylesheet, after `@import url(<chain>)` when `?chain=` is given;
+ * - `/uag-js/uag-js.css`: the stylesheet.
+ *
+ * The modules' components come after: each script after the registration in
+ * `uag.use.js` and `portal.js`, each stylesheet after `uag-js.css` (and in
+ * `portal.css`), and each on its own at `/uag-js/components/<type>.js|css`.
+ * They are read on every request, as the bundle is, so the ETag follows them.
+ */
+function uagJsRouter(registry, components = () => []) {
+    const router = (0, express_1.Router)();
+    const manifest = () => {
+        const plugins = registry();
+        // Every plugin the modules' components may read (document, converter, module, and types
+        // modules define): not the UAG's own engines, tools and actions, which /plugins lists.
+        return plugins ? plugins.manifest().filter((plugin) => !['engine', 'tool', 'action'].includes(plugin.type)) : [];
+    };
+    // Each component's script in its own try/catch, so one that fails when it runs does not stop the others.
+    // A script that does not parse would break the whole bundle, which try/catch cannot stop: it is left out.
+    const scripts = () => components().map((component) => {
+        const label = `The ${component.type} component of the ${component.module} module`;
+        const source = fs_1.default.readFileSync(component.scriptPath, 'utf8');
+        if (!parsesAsScript(component.scriptPath, source)) {
+            return `\n;/* ${component.module}: ${component.type} */\nconsole.error(${JSON.stringify(`[uag-js] ${label} is not a browser script (an ES module, or a syntax error), so it was left out.`)});\n`;
+        }
+        return `\n;/* ${component.module}: ${component.type} */\ntry {\n${source}\n} catch (err) { console.error(${JSON.stringify(`[uag-js] ${label} could not load:`)}, err); }\n`;
+    }).join('');
+    const styles = () => components().filter((component) => component.stylePath).map((component) => `\n/* ${component.module}: ${component.type} */\n${fs_1.default.readFileSync(component.stylePath, 'utf8')}`).join('');
+    const component = (type) => components().find((candidate) => candidate.type === type);
+    router.get('/uag-js/components/:file', (req, res) => {
+        const match = /^([a-z][a-z0-9]*)\.(js|css)$/.exec(String(req.params.file));
+        const found = match ? component(match[1]) : undefined;
+        const file = found && (match[2] === 'js' ? found.scriptPath : found.stylePath);
+        if (!file)
+            return res.status(404).type('text/plain').send('No module of this UAG has that component.');
+        serve(req, res, match[2] === 'js' ? 'application/javascript' : 'text/css', fs_1.default.readFileSync(file, 'utf8'));
+    });
+    const missing = (res) => res.status(404).type('text/plain').send('@formio/uag-js is not installed with this UAG.');
+    router.get('/uag-js/uag.use.js', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        serve(req, res, 'application/javascript', read('index.js') + registration(manifest(), { portal: false }) + scripts());
+    });
+    router.get('/uag-js/portal.js', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        serve(req, res, 'application/javascript', read('index.js') + registration(manifest(), { portal: true, chain: chainOf(req, ['https:']) }) + scripts());
+    });
+    router.get('/uag-js/portal.css', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        const chain = chainOf(req, ['https:', 'http:']);
+        serve(req, res, 'text/css', (chain ? `@import url(${JSON.stringify(chain)});\n` : '') + read('uag-js.css') + styles());
+    });
+    router.get('/uag-js/uag-js.css', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        serve(req, res, 'text/css', read('uag-js.css') + styles());
+    });
+    return router;
+}

package/lib/formflow.d.ts

@@ -0,0 +1,47 @@
+import { Formflow } from '@formio/appserver';
+/**
+ * Agentic Formflow from @formio/appserver-core, through @formio/appserver (see
+ * assertSingleCore), under the names the UAG uses. Internal to the UAG:
+ * applications reach Formflow as `Formflow` from this package's exports.
+ */
+export declare const EngineConfigError: typeof Formflow.EngineConfigError, EngineRegistry: typeof Formflow.EngineRegistry, FormflowError: typeof Formflow.FormflowError, FormflowService: typeof Formflow.FormflowService, RateLimitError: typeof Formflow.RateLimitError, ScopedTokenError: typeof Formflow.ScopedTokenError, bearerOf: typeof Formflow.bearerOf, engineRegistry: typeof Formflow.engineRegistry, formflow: typeof Formflow.formflow, formflowAuthenticate: typeof Formflow.formflowAuthenticate, identityOf: typeof Formflow.identityOf, issueScopedToken: typeof Formflow.issueScopedToken, isScopedToken: typeof Formflow.isScopedToken, readScopedToken: typeof Formflow.readScopedToken, resultEvent: typeof Formflow.resultEvent, withoutOwnedValues: typeof Formflow.withoutOwnedValues, callerKey: typeof Formflow.callerKey, stubAgentEngine: typeof Formflow.stubAgentEngine, stubDecisionEngine: typeof Formflow.stubDecisionEngine, toolsForScope: typeof Formflow.toolsForScope, EngineError: typeof Formflow.EngineError, formatReport: typeof Formflow.formatReport, flagOn: typeof Formflow.flagOn, flagOff: typeof Formflow.flagOff, ruleWithConstraints: typeof Formflow.ruleWithConstraints, describeBinary: typeof Formflow.describeBinary, isBinaryComponent: typeof Formflow.isBinaryComponent, fileMeta: typeof Formflow.fileMeta, plainTextReader: Formflow.FormflowFileReader, useDatabase: typeof Formflow.useDatabase, startEngines: typeof Formflow.startEngines, CHAT_INSTRUCTIONS: string, CHAT_REPLY: string, CHAT_CONFIRMED: string, CHAT_CHECK_TOOL: Formflow.ToolDefinition, LEASE_MS: number, RENEW_MS: number, MAX_ATTEMPTS: number;
+export type AgentEngine = Formflow.AgentEngine;
+export type TaskRunStatus = Formflow.TaskRunStatus;
+export type CoreTaskRunRecord<Id> = Formflow.TaskRunRecord<Id>;
+export type CoreNewTaskRun<Id> = Formflow.NewTaskRun<Id>;
+export type CoreTaskRunStore<Id> = Formflow.TaskRunStore<Id>;
+export type CallerIdentity = Formflow.CallerIdentity;
+export type DecisionEngine = Formflow.DecisionEngine;
+export type DecisionRequest = Formflow.DecisionRequest;
+export type EngineInstance = Formflow.EngineInstance;
+export type EngineRegistry = Formflow.EngineRegistry;
+export type ExtractRequest = Formflow.ExtractRequest;
+export type ExtractResponse = Formflow.ExtractResponse;
+export type FieldSpec = Formflow.FieldSpec;
+export type ToolCallResult = Formflow.ToolCallResult;
+export type ToolDefinition = Formflow.ToolDefinition;
+export type FormflowAgentApiConfig = Formflow.FormflowAgentApiConfig;
+export type FormflowConfig = Formflow.FormflowConfig;
+export type FormflowForm = Formflow.FormflowForm;
+export type FormflowHost = Formflow.FormflowHost;
+export type FormflowRateLimit = Formflow.FormflowRateLimit;
+export type FormflowRoutingConfig = Formflow.FormflowRoutingConfig;
+export type FormflowService = Formflow.FormflowService;
+export type FormflowTask = Formflow.FormflowTask;
+export type FormflowTool = Formflow.FormflowTool;
+export type FormflowFileReader = Formflow.FormflowFileReader;
+export type FormflowFileMeta = Formflow.FormflowFileMeta;
+export type FormflowFileContent = Formflow.FormflowFileContent;
+export type OperationContext = Formflow.OperationContext;
+export type OperationResult = Formflow.OperationResult;
+export type ScopedTokenClaims = Formflow.ScopedTokenClaims;
+/**
+ * Who an operation's research acts as: core's `identityOf`, and for a caller
+ * signed in with a Form.io token (`x-jwt-token`), that token, so a scoped token
+ * carries the user to /mcp as an `Authorization` bearer token would. A portal
+ * team member's remote token is never carried: research for them is refused,
+ * as it is for anonymous callers.
+ */
+export declare function callerIdentity(auth: any, req: {
+    get?: (name: string) => string | undefined;
+}): CallerIdentity;

package/lib/formflow.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ATTEMPTS = exports.RENEW_MS = exports.LEASE_MS = exports.CHAT_CHECK_TOOL = exports.CHAT_CONFIRMED = exports.CHAT_REPLY = exports.CHAT_INSTRUCTIONS = exports.startEngines = exports.useDatabase = exports.plainTextReader = exports.fileMeta = exports.isBinaryComponent = exports.describeBinary = exports.ruleWithConstraints = exports.flagOff = exports.flagOn = exports.formatReport = exports.EngineError = exports.toolsForScope = exports.stubDecisionEngine = exports.stubAgentEngine = exports.callerKey = exports.withoutOwnedValues = exports.resultEvent = exports.readScopedToken = exports.isScopedToken = exports.issueScopedToken = exports.identityOf = exports.formflowAuthenticate = exports.formflow = exports.engineRegistry = exports.bearerOf = exports.ScopedTokenError = exports.RateLimitError = exports.FormflowService = exports.FormflowError = exports.EngineRegistry = exports.EngineConfigError = void 0;
+exports.callerIdentity = callerIdentity;
+const appserver_1 = require("@formio/appserver");
+/**
+ * Agentic Formflow from @formio/appserver-core, through @formio/appserver (see
+ * assertSingleCore), under the names the UAG uses. Internal to the UAG:
+ * applications reach Formflow as `Formflow` from this package's exports.
+ */
+({ EngineConfigError: exports.EngineConfigError, EngineRegistry: exports.EngineRegistry, FormflowError: exports.FormflowError, FormflowService: exports.FormflowService, RateLimitError: exports.RateLimitError, ScopedTokenError: exports.ScopedTokenError, bearerOf: exports.bearerOf, engineRegistry: exports.engineRegistry, formflow: exports.formflow, formflowAuthenticate: exports.formflowAuthenticate, identityOf: exports.identityOf, issueScopedToken: exports.issueScopedToken, isScopedToken: exports.isScopedToken, readScopedToken: exports.readScopedToken, resultEvent: exports.resultEvent, withoutOwnedValues: exports.withoutOwnedValues, callerKey: exports.callerKey, stubAgentEngine: exports.stubAgentEngine, stubDecisionEngine: exports.stubDecisionEngine, toolsForScope: exports.toolsForScope, EngineError: exports.EngineError, formatReport: exports.formatReport, flagOn: exports.flagOn, flagOff: exports.flagOff, ruleWithConstraints: exports.ruleWithConstraints, describeBinary: exports.describeBinary, isBinaryComponent: exports.isBinaryComponent, fileMeta: exports.fileMeta, plainTextReader: exports.plainTextReader, useDatabase: exports.useDatabase, startEngines: exports.startEngines, CHAT_INSTRUCTIONS: exports.CHAT_INSTRUCTIONS, CHAT_REPLY: exports.CHAT_REPLY, CHAT_CONFIRMED: exports.CHAT_CONFIRMED, CHAT_CHECK_TOOL: exports.CHAT_CHECK_TOOL, LEASE_MS: exports.LEASE_MS, RENEW_MS: exports.RENEW_MS, MAX_ATTEMPTS: exports.MAX_ATTEMPTS } = appserver_1.Formflow);
+/**
+ * Who an operation's research acts as: core's `identityOf`, and for a caller
+ * signed in with a Form.io token (`x-jwt-token`), that token, so a scoped token
+ * carries the user to /mcp as an `Authorization` bearer token would. A portal
+ * team member's remote token is never carried: research for them is refused,
+ * as it is for anonymous callers.
+ */
+function callerIdentity(auth, req) {
+    const identity = (0, exports.identityOf)(auth, req.get?.('authorization'));
+    if (identity.admin || identity.bearer)
+        return identity;
+    const formioToken = req.get?.('x-jwt-token');
+    if (auth?.user && !auth.remoteToken && typeof formioToken === 'string' && formioToken) {
+        return { admin: false, bearer: formioToken };
+    }
+    return identity;
+}

package/lib/identity.d.ts

@@ -0,0 +1,53 @@
+import { AuthRequest } from '@formio/appserver';
+import { FormflowError } from './formflow';
+import type { UAGProjectInterface } from './UAGProjectInterface';
+/**
+ * Who the UAG acts as at Form.io when it runs a task for someone: the caller,
+ * with the token they sent, or a Run task action's agent role, acting on the
+ * caller's behalf with a Form.io token the UAG signs.
+ *
+ * The UAG signs Form.io "external" tokens with JWT_SECRET, which must be Form.io
+ * Enterprise's: Form.io then takes the user, and their roles, from the token. A
+ * token the UAG signs is short-lived, never marks an administrator, and never
+ * carries an admin role.
+ */
+/** Seconds a token the UAG signs is valid for. */
+export declare const SIGNED_TOKEN_TTL = 300;
+/** The user the UAG acts for: who sent the submission. No token, ever. */
+export type ActingFor = {
+    /** The user's id; none for an anonymous caller. */
+    _id?: string;
+    /** Their roles when they submitted. */
+    roles: string[];
+    email?: string;
+};
+/** What a token the UAG signs says about why it was signed (Form.io ignores it). */
+export type AgentClaim = {
+    agent: boolean;
+    action?: string;
+    task?: string;
+};
+/** A token the UAG may not sign, or Form.io would not accept. */
+export declare class AgentIdentityError extends FormflowError {
+    constructor(message: string);
+}
+/** The user a request comes from, as the UAG records it. */
+export declare function actingForOf(auth: AuthRequest | undefined, project: UAGProjectInterface): ActingFor;
+/**
+ * Sign a Form.io token for `user` with `roles`. Refuses an admin role, and never
+ * marks the holder an administrator.
+ */
+export declare function signFormioToken(project: UAGProjectInterface, user: ActingFor, roles: string[], claim: AgentClaim): string;
+/** An identity that acts as `role` for `user`, with a newly signed token. */
+export declare function agentAuth(project: UAGProjectInterface, user: ActingFor, role: string, claim: Omit<AgentClaim, 'agent'>): Promise<AuthRequest>;
+/**
+ * An identity that acts as `user`, with their recorded roles, for research and
+ * for the runs that act as them. A user's admin roles are left out: the UAG
+ * never signs a token with one, so the user acts with their other roles.
+ */
+export declare function userAuth(project: UAGProjectInterface, user: ActingFor, claim: Omit<AgentClaim, 'agent'>): Promise<AuthRequest>;
+/**
+ * Explain a Form.io refusal of a token the UAG signed: almost always a
+ * JWT_SECRET that is not Form.io Enterprise's.
+ */
+export declare function refusedSignedToken(status: number | undefined): AgentIdentityError | null;

package/lib/identity.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentIdentityError = exports.SIGNED_TOKEN_TTL = void 0;
+exports.actingForOf = actingForOf;
+exports.signFormioToken = signFormioToken;
+exports.agentAuth = agentAuth;
+exports.userAuth = userAuth;
+exports.refusedSignedToken = refusedSignedToken;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const appserver_1 = require("@formio/appserver");
+const formflow_1 = require("./formflow");
+/**
+ * Who the UAG acts as at Form.io when it runs a task for someone: the caller,
+ * with the token they sent, or a Run task action's agent role, acting on the
+ * caller's behalf with a Form.io token the UAG signs.
+ *
+ * The UAG signs Form.io "external" tokens with JWT_SECRET, which must be Form.io
+ * Enterprise's: Form.io then takes the user, and their roles, from the token. A
+ * token the UAG signs is short-lived, never marks an administrator, and never
+ * carries an admin role.
+ */
+/** Seconds a token the UAG signs is valid for. */
+exports.SIGNED_TOKEN_TTL = 300;
+/** A token the UAG may not sign, or Form.io would not accept. */
+class AgentIdentityError extends formflow_1.FormflowError {
+    constructor(message) {
+        super(500, message, 'agent_identity');
+        this.name = 'AgentIdentityError';
+    }
+}
+exports.AgentIdentityError = AgentIdentityError;
+/** The user a request comes from, as the UAG records it. */
+function actingForOf(auth, project) {
+    const user = auth?.user;
+    if (!user?._id) {
+        return { roles: project.anonymousRoles };
+    }
+    const email = user.data?.email;
+    return {
+        _id: String(user._id),
+        roles: (user.roles || []).map(String),
+        ...(typeof email === 'string' && { email })
+    };
+}
+/** The project's admin role ids, from its access settings. */
+function adminRoles(project) {
+    return new Set(Object.values(project.access?.roles || {})
+        .filter((role) => role?.admin)
+        .map((role) => String(role._id)));
+}
+/**
+ * Sign a Form.io token for `user` with `roles`. Refuses an admin role, and never
+ * marks the holder an administrator.
+ */
+function signFormioToken(project, user, roles, claim) {
+    const secret = project.config?.auth?.secret;
+    if (!secret)
+        throw new AgentIdentityError('Acting on behalf of a user needs JWT_SECRET, the same as Form.io Enterprise\'s.');
+    const admin = adminRoles(project);
+    if (roles.some((role) => admin.has(String(role)))) {
+        throw new AgentIdentityError('An agent cannot act with an admin role. Choose a role without admin access.');
+    }
+    const projectId = String(project.project?._id || '');
+    if (!projectId)
+        throw new AgentIdentityError('Acting on behalf of a user needs the project to be loaded.');
+    const payload = {
+        external: true,
+        // Form.io names an external user without an id from its data.
+        user: user._id
+            ? { _id: user._id, data: { ...(user.email && { email: user.email }) }, roles: roles.map(String) }
+            : { _id: 'external', data: { id: 'uag-anonymous' }, roles: roles.map(String) },
+        project: { _id: projectId },
+        uag: claim
+    };
+    return jsonwebtoken_1.default.sign(payload, secret, { expiresIn: exports.SIGNED_TOKEN_TTL });
+}
+/** An identity that acts as `role` for `user`, with a newly signed token. */
+async function agentAuth(project, user, role, claim) {
+    return authFor(project, user, [role], { agent: true, ...claim });
+}
+/**
+ * An identity that acts as `user`, with their recorded roles, for research and
+ * for the runs that act as them. A user's admin roles are left out: the UAG
+ * never signs a token with one, so the user acts with their other roles.
+ */
+async function userAuth(project, user, claim) {
+    const admin = adminRoles(project);
+    return authFor(project, user, user.roles.filter((role) => !admin.has(String(role))), { agent: false, ...claim });
+}
+async function authFor(project, user, roles, claim) {
+    const token = signFormioToken(project, user, roles, claim);
+    const auth = new appserver_1.AuthRequest(project);
+    await auth.fromFormioUser({ _id: user._id || 'external', roles, data: user.email ? { email: user.email } : {} }, token, project);
+    return auth;
+}
+/**
+ * Explain a Form.io refusal of a token the UAG signed: almost always a
+ * JWT_SECRET that is not Form.io Enterprise's.
+ */
+function refusedSignedToken(status) {
+    if (status !== 401 && status !== 440)
+        return null;
+    return new AgentIdentityError('Form.io refused the token the UAG signed to act on the user\'s behalf: JWT_SECRET must be the same as Form.io Enterprise\'s.');
+}