@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/database.d.ts

@@ -0,0 +1,70 @@
+import { Collection, Db, MongoClient, MongoClientOptions } from 'mongodb';
+import type { AuthCodeStore } from '@formio/appserver';
+/**
+ * The UAG's own database (MONGO, with the database named by UAG_DATABASE). It
+ * holds only the UAG's state: authorization codes for remote MCP clients, and
+ * task-run records. Never submissions.
+ *
+ * Every collection the UAG uses is named `uag-*`, and nothing else in the
+ * database is read or written, so the database may be shared. Before writing
+ * anything, the UAG checks that the `uag-*` collections are its own.
+ */
+/** The schema version this UAG writes. Older databases are migrated; newer ones refused. */
+export declare const UAG_SCHEMA_VERSION = 1;
+export declare const UAG_COLLECTIONS: Readonly<{
+    meta: "uag-meta";
+    authCodes: "uag-authcodes";
+    taskRuns: "uag-taskruns";
+}>;
+export type UAGDatabaseOptions = {
+    /** The connection string (MONGO). Its database, if any, is ignored: UAG_DATABASE names the one used. */
+    url: string;
+    /** The database to use (UAG_DATABASE). */
+    name?: string;
+    /** Driver options (MONGO_CONFIG), as JSON or an object. */
+    config?: string | MongoClientOptions;
+    /** Days a task-run record is kept (TASK_RUN_RETENTION_DAYS); 0 keeps it forever. */
+    retentionDays?: number;
+};
+/** Why the UAG may not use a database. Startup stops with this message. */
+export declare class UAGDatabaseError extends Error {
+    name: string;
+}
+export declare class UAGDatabase {
+    readonly client: MongoClient;
+    readonly db: Db;
+    readonly name: string;
+    readonly retentionDays: number;
+    private bootstrapped?;
+    private warned;
+    constructor(client: MongoClient, db: Db, options: UAGDatabaseOptions);
+    /**
+     * Connect, and select the database by name on the connection: the
+     * connection string's database and `authSource` are left as they are.
+     */
+    static connect(options: UAGDatabaseOptions): Promise<UAGDatabase>;
+    get meta(): Collection<any>;
+    get authCodes(): Collection<any>;
+    get taskRuns(): Collection<any>;
+    /**
+     * Check the database without writing anything: whether the UAG may use it,
+     * and what bootstrap would do. Refuses (throws) a database whose `uag-*`
+     * collections the UAG did not create, or that a newer UAG created.
+     */
+    inspect(): Promise<'fresh' | 'ready' | 'older'>;
+    /**
+     * Check the database (see inspect), then create what is missing: the schema
+     * marker first, then the collections and their indexes; or migrate an older
+     * schema. Safe to call again.
+     */
+    bootstrap(): Promise<'created' | 'ready' | 'migrated'>;
+    /** Create the collections and indexes, as needed; safe to repeat. */
+    private ensureCollections;
+    /** The task-run records' TTL index, following TASK_RUN_RETENTION_DAYS; none when it is 0. */
+    private ensureRetention;
+    /** Run database work, reporting a missing privilege with the database's name. */
+    private privileged;
+    /** Authorization codes for remote MCP clients (MCP_OAUTH), in `uag-authcodes`. */
+    authCodeStore(): AuthCodeStore;
+    close(): Promise<void>;
+}

package/lib/database.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAGDatabase = exports.UAGDatabaseError = exports.UAG_COLLECTIONS = exports.UAG_SCHEMA_VERSION = void 0;
+const crypto_1 = require("crypto");
+const mongodb_1 = require("mongodb");
+const debug = require('debug')('formio:uag:database');
+/**
+ * The UAG's own database (MONGO, with the database named by UAG_DATABASE). It
+ * holds only the UAG's state: authorization codes for remote MCP clients, and
+ * task-run records. Never submissions.
+ *
+ * Every collection the UAG uses is named `uag-*`, and nothing else in the
+ * database is read or written, so the database may be shared. Before writing
+ * anything, the UAG checks that the `uag-*` collections are its own.
+ */
+/** The schema version this UAG writes. Older databases are migrated; newer ones refused. */
+exports.UAG_SCHEMA_VERSION = 1;
+exports.UAG_COLLECTIONS = Object.freeze({
+    meta: 'uag-meta',
+    authCodes: 'uag-authcodes',
+    taskRuns: 'uag-taskruns',
+});
+const PREFIX = 'uag-';
+const APP = 'formio-uag';
+const SCHEMA_ID = 'schema';
+const RETENTION_INDEX = 'retention';
+const DEFAULT_RETENTION_DAYS = 90;
+// MongoDB's "Unauthorized" error.
+const UNAUTHORIZED = 13;
+/** Why the UAG may not use a database. Startup stops with this message. */
+class UAGDatabaseError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'UAGDatabaseError';
+    }
+}
+exports.UAGDatabaseError = UAGDatabaseError;
+function driverOptions(config) {
+    if (!config)
+        return {};
+    if (typeof config !== 'string')
+        return config;
+    try {
+        return JSON.parse(config);
+    }
+    catch (err) {
+        throw new UAGDatabaseError(`MONGO_CONFIG is not valid JSON: ${err.message}`);
+    }
+}
+/** Authorization codes are stored by their hash, so the database never holds a usable code. */
+const codeKey = (code) => (0, crypto_1.createHash)('sha256').update(code).digest('base64url');
+/**
+ * An authorization code's token, sealed with a key only the code gives: the
+ * database holds neither the code nor a token it could use.
+ */
+const sealKey = (code) => (0, crypto_1.createHash)('sha256').update(`uag-authcode:${code}`).digest();
+function sealToken(code, token) {
+    const iv = (0, crypto_1.randomBytes)(12);
+    const cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', sealKey(code), iv);
+    const sealed = Buffer.concat([cipher.update(token, 'utf8'), cipher.final()]);
+    return [iv, cipher.getAuthTag(), sealed].map((part) => part.toString('base64url')).join('.');
+}
+function openToken(code, sealed) {
+    try {
+        const [iv, tag, data] = sealed.split('.').map((part) => Buffer.from(part, 'base64url'));
+        const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', sealKey(code), iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+class UAGDatabase {
+    constructor(client, db, options) {
+        this.client = client;
+        this.db = db;
+        this.warned = false;
+        this.name = db.databaseName;
+        const days = options.retentionDays;
+        this.retentionDays = days === undefined || Number.isNaN(days) ? DEFAULT_RETENTION_DAYS : Math.max(0, days);
+    }
+    /**
+     * Connect, and select the database by name on the connection: the
+     * connection string's database and `authSource` are left as they are.
+     */
+    static async connect(options) {
+        const name = options.name || 'uag';
+        const client = new mongodb_1.MongoClient(options.url, driverOptions(options.config));
+        try {
+            await client.connect();
+        }
+        catch (err) {
+            throw new UAGDatabaseError(`Could not connect to MONGO: ${err.message}`);
+        }
+        return new UAGDatabase(client, client.db(name), { ...options, name });
+    }
+    get meta() { return this.db.collection(exports.UAG_COLLECTIONS.meta); }
+    get authCodes() { return this.db.collection(exports.UAG_COLLECTIONS.authCodes); }
+    get taskRuns() { return this.db.collection(exports.UAG_COLLECTIONS.taskRuns); }
+    /**
+     * Check the database without writing anything: whether the UAG may use it,
+     * and what bootstrap would do. Refuses (throws) a database whose `uag-*`
+     * collections the UAG did not create, or that a newer UAG created.
+     */
+    async inspect() {
+        return this.privileged(async () => {
+            const names = (await this.db.listCollections({}, { nameOnly: true }).toArray()).map((info) => info.name);
+            const ours = names.filter((name) => name.startsWith(PREFIX));
+            if (names.length > ours.length && !this.warned) {
+                this.warned = true;
+                console.warn(`[formio-uag] The database "${this.name}" holds other data too. The UAG uses only its uag-* collections there, ` +
+                    'but a database of its own is recommended (UAG_DATABASE).');
+            }
+            if (!ours.length)
+                return 'fresh';
+            const marker = ours.includes(exports.UAG_COLLECTIONS.meta) ? await this.meta.findOne({ _id: SCHEMA_ID }) : null;
+            if (!marker || marker.app !== APP || typeof marker.version !== 'number') {
+                throw new UAGDatabaseError(`The database "${this.name}" holds uag-* collections that the UAG did not create (${ours.join(', ')}). ` +
+                    'Nothing was changed. Choose another database with UAG_DATABASE.');
+            }
+            if (marker.version > exports.UAG_SCHEMA_VERSION) {
+                throw new UAGDatabaseError(`The database "${this.name}" was created by a newer UAG (schema version ${marker.version}; ` +
+                    `this UAG supports ${exports.UAG_SCHEMA_VERSION}). Upgrade the UAG, or choose another database with UAG_DATABASE.`);
+            }
+            return marker.version < exports.UAG_SCHEMA_VERSION ? 'older' : 'ready';
+        });
+    }
+    /**
+     * Check the database (see inspect), then create what is missing: the schema
+     * marker first, then the collections and their indexes; or migrate an older
+     * schema. Safe to call again.
+     */
+    bootstrap() {
+        this.bootstrapped = this.bootstrapped || this.privileged(async () => {
+            const state = await this.inspect();
+            if (state === 'fresh') {
+                // The marker first: a start interrupted after it finishes the rest next time.
+                await this.meta.insertOne({ _id: SCHEMA_ID, app: APP, version: exports.UAG_SCHEMA_VERSION, created: new Date() });
+                await this.ensureCollections();
+                debug(`Created the UAG's collections in "${this.name}".`);
+                return 'created';
+            }
+            await this.ensureCollections();
+            if (state === 'older') {
+                // No migrations yet: each schema version adds its steps here.
+                await this.meta.updateOne({ _id: SCHEMA_ID }, { $set: { version: exports.UAG_SCHEMA_VERSION, migrated: new Date() } });
+                return 'migrated';
+            }
+            return 'ready';
+        });
+        // A failed attempt can be tried again.
+        this.bootstrapped.catch(() => { this.bootstrapped = undefined; });
+        return this.bootstrapped;
+    }
+    /** Create the collections and indexes, as needed; safe to repeat. */
+    async ensureCollections() {
+        await this.authCodes.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0, name: 'expires' });
+        await this.taskRuns.createIndex({ status: 1, leaseUntil: 1 }, { name: 'claim' });
+        await this.taskRuns.createIndex({ project: 1, form: 1, submission: 1, created: -1 }, { name: 'submission' });
+        await this.ensureRetention();
+    }
+    /** The task-run records' TTL index, following TASK_RUN_RETENTION_DAYS; none when it is 0. */
+    async ensureRetention() {
+        const seconds = this.retentionDays * 24 * 60 * 60;
+        const indexes = await this.taskRuns.listIndexes().toArray().catch(() => []);
+        const existing = indexes.find((index) => index.name === RETENTION_INDEX);
+        if (!seconds) {
+            if (existing)
+                await this.taskRuns.dropIndex(RETENTION_INDEX);
+            return;
+        }
+        if (!existing) {
+            await this.taskRuns.createIndex({ created: 1 }, { expireAfterSeconds: seconds, name: RETENTION_INDEX });
+        }
+        else if (existing.expireAfterSeconds !== seconds) {
+            await this.db.command({ collMod: exports.UAG_COLLECTIONS.taskRuns, index: { name: RETENTION_INDEX, expireAfterSeconds: seconds } });
+        }
+    }
+    /** Run database work, reporting a missing privilege with the database's name. */
+    async privileged(work) {
+        try {
+            return await work();
+        }
+        catch (err) {
+            if (err?.code === UNAUTHORIZED) {
+                throw new UAGDatabaseError(`The MONGO user may not use the database "${this.name}" (${err.message}). ` +
+                    `Grant it the readWrite role on "${this.name}", or choose another database with UAG_DATABASE.`);
+            }
+            throw err;
+        }
+    }
+    /** Authorization codes for remote MCP clients (MCP_OAUTH), in `uag-authcodes`. */
+    authCodeStore() {
+        const collection = this.authCodes;
+        return {
+            async save(code, record, ttl) {
+                await collection.insertOne({ _id: codeKey(code), sealed: sealToken(code, record.jwt), codeChallenge: record.codeChallenge, expiresAt: new Date(Date.now() + ttl * 1000) });
+            },
+            async take(code) {
+                // The TTL monitor runs about once a minute, so expiry is checked here too.
+                const found = await collection.findOneAndDelete({ _id: codeKey(code), expiresAt: { $gt: new Date() } });
+                const jwt = typeof found?.sealed === 'string' ? openToken(code, found.sealed) : null;
+                return jwt ? { jwt, codeChallenge: found.codeChallenge } : null;
+            }
+        };
+    }
+    async close() {
+        await this.client.close();
+    }
+}
+exports.UAGDatabase = UAGDatabase;

package/lib/documents/convert.d.ts

@@ -0,0 +1,38 @@
+import type { PluginContext } from '@formio/appserver';
+import type { Converter, ConverterOutput, Representation } from './types';
+export declare const CONVERTER_DEFAULTS: {
+    maxBytes: number;
+    timeoutMs: number;
+    concurrency: number;
+};
+/** A conversion that did not complete. The message names the converter and the file, never its content. */
+export declare class ConversionError extends Error {
+    constructor(message: string);
+}
+export type ConvertOptions = {
+    to: Representation;
+    settings?: Record<string, any>;
+    signal?: AbortSignal;
+    log: PluginContext['log'];
+};
+/**
+ * Run one conversion: under the converter's size limit, in a temporary
+ * directory made for the call and removed after it, aborted at its timeout,
+ * and queued behind its other conversions beyond its concurrency.
+ */
+export declare function runConverter(converter: Converter, input: {
+    buffer: Buffer;
+    type: string;
+    name: string;
+}, options: ConvertOptions): Promise<ConverterOutput>;
+/**
+ * Run a route: each step's output feeds the next (an intermediate step always
+ * makes a PDF), with each converter's operator settings.
+ */
+export declare function runRoute(steps: Converter[], input: {
+    buffer: Buffer;
+    type: string;
+    name: string;
+}, to: Representation, options: Omit<ConvertOptions, 'to' | 'settings'> & {
+    settingsOf?: (converter: Converter) => Record<string, any> | undefined;
+}): Promise<ConverterOutput>;

package/lib/documents/convert.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversionError = exports.CONVERTER_DEFAULTS = void 0;
+exports.runConverter = runConverter;
+exports.runRoute = runRoute;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+exports.CONVERTER_DEFAULTS = { maxBytes: 25 * 1024 * 1024, timeoutMs: 120000, concurrency: 2 };
+/** A conversion that did not complete. The message names the converter and the file, never its content. */
+class ConversionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConversionError';
+    }
+}
+exports.ConversionError = ConversionError;
+/**
+ * A queue per converter, so at most `concurrency` of its conversions run at
+ * once. A slot is held until its conversion has actually stopped: a converter
+ * that ignores its signal still counts after its caller has given up on it.
+ */
+class Queue {
+    constructor(limit) {
+        this.limit = limit;
+        this.running = 0;
+        this.waiting = [];
+    }
+    /** Wait for a slot; the returned function frees it (once). */
+    async acquire(signal) {
+        signal?.throwIfAborted();
+        if (this.running < this.limit) {
+            this.running++;
+        }
+        else {
+            // A freed slot passes straight to the next waiter, so no new caller can take it in between.
+            await new Promise((resolve, reject) => {
+                const go = () => { signal?.removeEventListener('abort', cancel); resolve(); };
+                const cancel = () => { this.waiting = this.waiting.filter((entry) => entry !== go); reject(signal.reason ?? new Error('aborted')); };
+                this.waiting.push(go);
+                signal?.addEventListener('abort', cancel, { once: true });
+            });
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const next = this.waiting.shift();
+            if (next)
+                next();
+            else
+                this.running--;
+        };
+    }
+}
+const queues = new WeakMap();
+/**
+ * Run one conversion: under the converter's size limit, in a temporary
+ * directory made for the call and removed after it, aborted at its timeout,
+ * and queued behind its other conversions beyond its concurrency.
+ */
+async function runConverter(converter, input, options) {
+    const limits = { ...exports.CONVERTER_DEFAULTS, ...(converter.limits || {}) };
+    if (input.buffer.length > limits.maxBytes) {
+        throw new ConversionError(`"${input.name}" is larger than the ${converter.name} converter takes (${limits.maxBytes} bytes).`);
+    }
+    let queue = queues.get(converter);
+    if (!queue) {
+        queue = new Queue(Math.max(1, limits.concurrency));
+        queues.set(converter, queue);
+    }
+    const release = await queue.acquire(options.signal);
+    let tmpdir;
+    try {
+        options.signal?.throwIfAborted();
+        tmpdir = await fs_1.default.promises.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'uag-convert-'));
+    }
+    catch (err) {
+        release();
+        throw err;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    const work = Promise.resolve().then(() => converter.convert(input, { to: options.to, settings: options.settings || {}, signal: controller.signal, tmpdir, log: options.log }));
+    // The slot and the temporary directory are kept until convert() settles, even after a timeout or an abort.
+    const stopped = work.then(() => undefined, () => undefined).then(async () => {
+        await fs_1.default.promises.rm(tmpdir, { recursive: true, force: true }).catch(() => undefined);
+        release();
+    });
+    let timer;
+    let finished = false;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                const error = new ConversionError(`Converting "${input.name}" with ${converter.name} took longer than ${limits.timeoutMs} ms.`);
+                // Abort first: a converter running a process stops it on its signal.
+                controller.abort(error);
+                reject(error);
+            }, limits.timeoutMs);
+        });
+        const aborted = new Promise((_, reject) => {
+            if (controller.signal.aborted)
+                reject(controller.signal.reason);
+            controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
+        });
+        const output = await Promise.race([work.finally(() => { finished = true; }), timeout, aborted]);
+        return checkOutput(converter, input.name, options.to, output);
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+        // A conversion that completed has its directory removed before its result is used.
+        if (finished)
+            await stopped;
+    }
+}
+function checkOutput(converter, name, to, output) {
+    if (to === 'pdf') {
+        if (!output || !Buffer.isBuffer(output.pdf))
+            throw new ConversionError(`The ${converter.name} converter did not produce a PDF for "${name}".`);
+        return output;
+    }
+    if (!output || typeof output.text !== 'string' || !['plain', 'markdown', 'csv'].includes(output.textFormat)) {
+        throw new ConversionError(`The ${converter.name} converter did not produce text for "${name}".`);
+    }
+    return output;
+}
+/**
+ * Run a route: each step's output feeds the next (an intermediate step always
+ * makes a PDF), with each converter's operator settings.
+ */
+async function runRoute(steps, input, to, options) {
+    let current = input;
+    let output;
+    for (let i = 0; i < steps.length; i++) {
+        const target = i === steps.length - 1 ? to : 'pdf';
+        output = await runConverter(steps[i], current, { ...options, to: target, settings: options.settingsOf?.(steps[i]) });
+        if (target === 'pdf')
+            current = { buffer: output.pdf, type: 'application/pdf', name: input.name };
+    }
+    if (!output)
+        throw new ConversionError(`No converter step for "${input.name}".`);
+    return output;
+}

package/lib/documents/converters.d.ts

@@ -0,0 +1,28 @@
+import type { Converter } from './types';
+/** unpdf, loaded on first use: it is an ES module, and carries a PDF.js build. */
+export declare function loadUnpdf(): Promise<typeof import('unpdf')>;
+/** pdf-text: a PDF's text layer, page by page, with unpdf. */
+export declare const pdfTextConverter: Converter;
+/** Decode text: UTF-16 with a byte order mark, else UTF-8 (without its BOM), else Windows-1252 (a superset of Latin-1). */
+export declare function decodeText(buffer: Buffer): string;
+/** text: plain text, Markdown, CSV, JSON, HTML (as Markdown) and XML. */
+export declare const textConverter: Converter;
+/**
+ * The most pixels of a PNG image-pdf takes (50 megapixels, about 200 MB once
+ * decoded). A PNG is decoded whole, in memory and synchronously, so its pixel
+ * count is checked from its header first: a small, highly compressed file can
+ * describe an image far larger than its size suggests. JPEGs are embedded
+ * without being decoded. The converter's `maxPixels` setting changes it
+ * (config.plugins.settings.converter['image-pdf'].maxPixels, or
+ * DOCUMENTS_MAX_IMAGE_PIXELS).
+ */
+export declare const MAX_IMAGE_PIXELS = 50000000;
+/** A PNG's width and height, from its IHDR header; undefined when it has none. */
+export declare function pngSize(buffer: Buffer): {
+    width: number;
+    height: number;
+} | undefined;
+/** image-pdf: PNG and JPEG images into a PDF, one page per image, scaled to fit and never resampled. */
+export declare const imagePdfConverter: Converter;
+/** The converters every UAG has. None needs a system binary. */
+export declare const BUILT_IN_CONVERTERS: Converter[];

package/lib/documents/converters.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILT_IN_CONVERTERS = exports.imagePdfConverter = exports.MAX_IMAGE_PIXELS = exports.textConverter = exports.pdfTextConverter = void 0;
+exports.loadUnpdf = loadUnpdf;
+exports.decodeText = decodeText;
+exports.pngSize = pngSize;
+const node_html_markdown_1 = require("node-html-markdown");
+const mime_1 = require("./mime");
+const convert_1 = require("./convert");
+const version_1 = require("../version");
+/**
+ * A real dynamic import: TypeScript compiles `import()` in a CommonJS build to
+ * `require()`, which cannot load an ES module before Node 22.12.
+ */
+const esmImport = new Function('specifier', 'return import(specifier)');
+/** unpdf, loaded on first use: it is an ES module, and carries a PDF.js build. */
+function loadUnpdf() {
+    return esmImport('unpdf');
+}
+/** pdf-text: a PDF's text layer, page by page, with unpdf. */
+exports.pdfTextConverter = {
+    type: 'converter',
+    name: 'pdf-text',
+    title: 'PDF text',
+    description: 'The text layer of a PDF, page by page. A PDF without one (a scan) yields empty text and a warning.',
+    version: version_1.UAG_VERSION,
+    apiVersion: 1,
+    accepts: [{ type: mime_1.MIME.pdf, ext: ['.pdf'] }],
+    produces: ['text'],
+    async convert(input, options) {
+        options.signal.throwIfAborted();
+        const { extractText, getDocumentProxy } = await loadUnpdf();
+        const document = await getDocumentProxy(new Uint8Array(input.buffer));
+        const { totalPages, text } = await extractText(document, { mergePages: false });
+        const pages = text.map((pageText, i) => ({ page: i + 1, text: String(pageText || '').trim() }));
+        const all = pages.map((page) => page.text).join('\n\n').trim();
+        return {
+            text: all,
+            textFormat: 'plain',
+            pages,
+            ...(!all && { warnings: [`"${input.name}" has no text layer (${totalPages} page${totalPages === 1 ? '' : 's'}): it may be a scan.`] })
+        };
+    }
+};
+/** Decode text: UTF-16 with a byte order mark, else UTF-8 (without its BOM), else Windows-1252 (a superset of Latin-1). */
+function decodeText(buffer) {
+    if (buffer[0] === 0xff && buffer[1] === 0xfe)
+        return new TextDecoder('utf-16le').decode(buffer.subarray(2));
+    if (buffer[0] === 0xfe && buffer[1] === 0xff)
+        return new TextDecoder('utf-16be').decode(buffer.subarray(2));
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buffer).replace(/^\uFEFF/, '');
+    }
+    catch {
+        return new TextDecoder('windows-1252').decode(buffer);
+    }
+}
+const TEXT_FORMATS = {
+    [mime_1.MIME.markdown]: 'markdown',
+    [mime_1.MIME.html]: 'markdown',
+    [mime_1.MIME.csv]: 'csv'
+};
+/** text: plain text, Markdown, CSV, JSON, HTML (as Markdown) and XML. */
+exports.textConverter = {
+    type: 'converter',
+    name: 'text',
+    title: 'Text',
+    description: 'Text files as they are; HTML as Markdown.',
+    version: version_1.UAG_VERSION,
+    apiVersion: 1,
+    accepts: [
+        { type: mime_1.MIME.text, ext: ['.txt'] },
+        { type: mime_1.MIME.markdown, ext: ['.md', '.markdown'] },
+        { type: mime_1.MIME.csv, ext: ['.csv'] },
+        { type: mime_1.MIME.json, ext: ['.json'] },
+        { type: mime_1.MIME.html, ext: ['.html', '.htm'] },
+        { type: mime_1.MIME.xml, ext: ['.xml'] }
+    ],
+    produces: ['text'],
+    async convert(input, options) {
+        options.signal.throwIfAborted();
+        const decoded = decodeText(input.buffer);
+        const text = input.type === mime_1.MIME.html ? node_html_markdown_1.NodeHtmlMarkdown.translate(decoded) : decoded;
+        return { text, textFormat: TEXT_FORMATS[input.type] || 'plain' };
+    }
+};
+/** A4 portrait, in points. */
+const PAGE = { width: 595.28, height: 841.89, margin: 36 };
+/**
+ * The most pixels of a PNG image-pdf takes (50 megapixels, about 200 MB once
+ * decoded). A PNG is decoded whole, in memory and synchronously, so its pixel
+ * count is checked from its header first: a small, highly compressed file can
+ * describe an image far larger than its size suggests. JPEGs are embedded
+ * without being decoded. The converter's `maxPixels` setting changes it
+ * (config.plugins.settings.converter['image-pdf'].maxPixels, or
+ * DOCUMENTS_MAX_IMAGE_PIXELS).
+ */
+exports.MAX_IMAGE_PIXELS = 50000000;
+/** A PNG's width and height, from its IHDR header; undefined when it has none. */
+function pngSize(buffer) {
+    if (buffer.length < 24 || buffer.toString('latin1', 12, 16) !== 'IHDR')
+        return undefined;
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+/** image-pdf: PNG and JPEG images into a PDF, one page per image, scaled to fit and never resampled. */
+exports.imagePdfConverter = {
+    type: 'converter',
+    name: 'image-pdf',
+    title: 'Image to PDF',
+    description: 'A PNG or JPEG image as a one-page PDF, scaled to fit the page.',
+    version: version_1.UAG_VERSION,
+    apiVersion: 1,
+    accepts: [{ type: mime_1.MIME.png, ext: ['.png'] }, { type: mime_1.MIME.jpeg, ext: ['.jpg', '.jpeg'] }],
+    produces: ['pdf'],
+    settings: {
+        maxPixels: {
+            type: 'number',
+            env: 'DOCUMENTS_MAX_IMAGE_PIXELS',
+            default: exports.MAX_IMAGE_PIXELS,
+            description: 'The largest PNG, in pixels (width × height), converted; a larger one is refused before it is decoded.'
+        }
+    },
+    async convert(input, options) {
+        options.signal.throwIfAborted();
+        if (input.type === mime_1.MIME.png) {
+            const size = pngSize(input.buffer);
+            if (!size)
+                throw new convert_1.ConversionError(`"${input.name}" is not a PNG image the image-pdf converter can read.`);
+            const maxPixels = Number(options.settings?.maxPixels) > 0 ? Number(options.settings.maxPixels) : exports.MAX_IMAGE_PIXELS;
+            if (size.width * size.height > maxPixels) {
+                throw new convert_1.ConversionError(`"${input.name}" is ${size.width}×${size.height} pixels, more than the image-pdf converter takes (${maxPixels} pixels).`);
+            }
+        }
+        const { PDFDocument } = require('pdf-lib');
+        const pdf = await PDFDocument.create();
+        const image = input.type === mime_1.MIME.png ? await pdf.embedPng(input.buffer) : await pdf.embedJpg(input.buffer);
+        const landscape = image.width > image.height;
+        const width = landscape ? PAGE.height : PAGE.width;
+        const height = landscape ? PAGE.width : PAGE.height;
+        const scale = Math.min(1, (width - 2 * PAGE.margin) / image.width, (height - 2 * PAGE.margin) / image.height);
+        const page = pdf.addPage([width, height]);
+        const drawn = { width: image.width * scale, height: image.height * scale };
+        // The image is embedded as it is and only drawn smaller: its pixels are never resampled.
+        page.drawImage(image, { x: (width - drawn.width) / 2, y: (height - drawn.height) / 2, ...drawn });
+        return { pdf: Buffer.from(await pdf.save()), pages: 1 };
+    }
+};
+/** The converters every UAG has. None needs a system binary. */
+exports.BUILT_IN_CONVERTERS = [exports.pdfTextConverter, exports.textConverter, exports.imagePdfConverter];