@oneentry/mcp-platform-server 0.1.4 → 0.1.6

package/dist/api/operation-notes.js

@@ -0,0 +1,394 @@
+export const ALWAYS_CONFIRM_PREFIXES = [
+    '/immutable-settings',
+    '/admins',
+    '/backups',
+    '/modules',
+    '/payments/webhook',
+    '/auth/logout/all-users',
+    '/settings-general',
+    '/system/captcha-keys',
+];
+const LIST_ATTRIBUTE_WITH_EXTRAS = {
+    type: 'list',
+    identifier: 'labels',
+    multiselect: true,
+    localizeInfos: { en_US: { title: 'Labels' } },
+    listTitles: {
+        en_US: [
+            {
+                title: 'Dishwasher safe',
+                value: 'dishwasher-safe',
+                position: 1,
+                extended: {
+                    type: 'image',
+                    value: {
+                        filename: 'dishwasher-safe.png',
+                        downloadLink: 'https://your-instance.example/files/dishwasher-safe.png',
+                    },
+                },
+            },
+            {
+                title: 'Cherry',
+                value: 'cherry',
+                position: 2,
+                extended: { type: 'string', value: '#d11241' },
+            },
+        ],
+    },
+};
+const LIST_EXTRAS_NOTE = 'The curated example is ONE attribute as it appears in the set\'s schema list. Three ' +
+    'details in it are each enough on their own to leave the field blank in the admin panel ' +
+    'while every read returns exactly what you sent. "extended" carries NO locale key — it is ' +
+    'flat, "type" and "value", and it is the one exception to the locale-first rule that ' +
+    'applies to "localizeInfos", "validators" and "listTitles" around it. Its "type" is one of ' +
+    'string, integer, realNumber, fixedPointNumber, date, dateAndTime, time, image, file, json, ' +
+    'and for image or file the value is ONE object, not a list. "multiselect": true belongs to ' +
+    'the attribute: without it every selected option is stored and read back, and the panel ' +
+    'shows only the first one. Two neighbouring fields look right and are not: ' +
+    '"additionalFields" is a separate marker-keyed list of fields and holds no option extras, ' +
+    'and an "image" key on the option itself is stored and read by nothing. Option extras are ' +
+    'also absent from entity reads — a site gets them from the attribute definition, not from ' +
+    'the product.';
+export const OPERATION_NOTES = {
+    AdminProductsController_findAll: {
+        readOnly: true,
+        note: 'Pagination and locale are query parameters, not body fields: pass limit, offset and ' +
+            'langCode in "query". The body is an ARRAY of filter objects — send [] for no filter. ' +
+            'A body of { limit, offset, langCode } answers 400 complaining about langCode, because ' +
+            'the validator is describing the query parameter you did not send.',
+    },
+    AdminProductsController_setStatusForProducts: {
+        silentNoOp: 'The status id goes in "id", not "statusId". With "statusId" the handler reads ' +
+            'undefined, writes NULL over the product status and still answers 201 true. The call ' +
+            'also never re-indexes, so even a correct write stays invisible to ' +
+            'AdminProductsController_findAll. Setting statusId through ' +
+            'AdminProductsController_update is the route that works today.',
+        verifyWith: {
+            opId: 'AdminProductsController_findOne',
+            check: 'statusId',
+            why: 'the call answers 201 true whether or not any row changed',
+        },
+    },
+    AdminAttributesSetsController_create: {
+        note: 'Inside an attribute, "validators", "localizeInfos" and "listTitles" are keyed by ' +
+            'locale first: validators.en_US.requiredValidator, not validators.requiredValidator. ' +
+            'A flat map is stored verbatim and read by nobody. ' +
+            LIST_EXTRAS_NOTE,
+        example: LIST_ATTRIBUTE_WITH_EXTRAS,
+        verifyWith: {
+            opId: 'AdminAttributesSetsController_findOne',
+            check: 'schema[].validators.<locale>',
+            why: 'the raw set shows exactly what you wrote, including a flat map that no consumer reads',
+        },
+    },
+    AdminAttributesSetsController_update: {
+        note: 'Inside an attribute, "validators", "localizeInfos" and "listTitles" are keyed by ' +
+            'locale first. A flat map is accepted and stored where nothing reads it. ' +
+            'Dropping an attribute from the set does not remove the values entities already hold ' +
+            'under its key: they stay on every entity, are invisible in the panel, and a ' +
+            'read-modify-write cycle sends them back, so they outlive the attribute indefinitely. ' +
+            'Strip the removed keys from each entity yourself, in the same run. ' +
+            LIST_EXTRAS_NOTE,
+        example: LIST_ATTRIBUTE_WITH_EXTRAS,
+        verifyWith: {
+            opId: 'AdminAttributesSetsController_findOne',
+            check: 'schema[].validators.<locale>',
+            why: 'the raw set shows what you wrote; the projection a site reads shows what it gets',
+        },
+    },
+    AdminAttributesSetsController_updateSchema: {
+        note: 'The body is the schema object itself, never wrapped as { "schema": … }. The wrapped ' +
+            'form answers 200 and replaces the set with a single attribute called "schema". ' +
+            'Locale-keyed rules apply here too, and so does the residue rule: an attribute removed ' +
+            'here leaves its values on every entity that had one. ' +
+            LIST_EXTRAS_NOTE,
+        example: LIST_ATTRIBUTE_WITH_EXTRAS,
+        verifyWith: {
+            opId: 'AdminAttributesSetsController_findOne',
+            check: 'schema[].validators.<locale>',
+            why: 'a wrapped or flat body answers 200 and destroys or discards what you sent',
+        },
+    },
+    AdminFileUploadController_uploadFiles: {
+        note: 'The body is multipart, so cms_api_call cannot send it — use cms_upload_file for a file ' +
+            'on the machine running this server, or cms_import_file_from_url to have the server ' +
+            'fetch it. Both keep the allow level, the confirm gate and the audit line. The binary ' +
+            'part is accepted under "file" and under "files" alike; everything else — type, entity, ' +
+            'id, compress, edit, template — is a query parameter. The "template" parameter is the ' +
+            'NUMERIC id of a /template-previews record, not a boolean flag. A fresh instance has no ' +
+            'such records, and an upload without a valid template id stores the file with no preview ' +
+            'and reports no error; the only repair is uploading the file again. That matters because ' +
+            'previewLink.default[0] is the inline placeholder a site renders while the full image ' +
+            'loads, so an image without it cannot be shown progressively. The stored record carries ' +
+            'no "alt" and no "title": alternative text has to live in a sibling attribute, and the ' +
+            'project has to agree on one naming convention for it before the first upload.',
+    },
+    AdminMenusController_create: {
+        note: 'Create the menu with an empty pagesIds, then attach pages with AdminMenusController_update. ' +
+            'A non-empty pagesIds on create answers 500 (null value in column "page_id"). That 500 is ' +
+            'known — do not report it as an unexplained server failure.',
+    },
+    AdminMenusController_update: {
+        note: '"pagesIds" is a flat set of page ids and nothing else: nesting is NOT taken from the ' +
+            'page tree, so a menu whose pages are nested in the content tree still reads back flat. ' +
+            'Build the levels afterwards, top down, with the position operations. A page can appear ' +
+            'in the set once — a page that has to sit in two places gets a custom item with the same ' +
+            'target for the second one, otherwise one of the two silently disappears. The label a ' +
+            'menu item shows is the page\'s "menuTitle", not its "title", so a menu built without ' +
+            'setting menuTitle arrives carrying page headings.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the included pages, their parents and their labels',
+            why: 'the update answers 200 for a flat result as readily as for the tree you intended',
+        },
+    },
+    AdminMenusController_createCustomItem: {
+        note: 'A custom item is for anything that is not a page: a product, an external address, a ' +
+            'column heading. An empty "value" is rejected, so a heading with no link needs a ' +
+            'placeholder target such as "#". The parent reference is a bare number with no kind ' +
+            'attached, while custom items and page items are numbered separately — so a custom item ' +
+            'and a page item can share an id, and children hung on that number are then returned ' +
+            'under BOTH parents. Before nesting anything, read the menu and check that the included ' +
+            'pages and the custom items share no id; if they do, the only route today is to recreate ' +
+            'the custom item until its id differs.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the ids of included pages against the ids of customItems',
+            why: 'a shared id duplicates a whole branch, and the write that caused it answers 200',
+        },
+    },
+    AdminMenusController_updatePosition: {
+        example: { position: { leftObjectId: null, rightObjectId: null }, newParentId: 12 },
+        note: '"position" is required even when the order does not matter, and it must be an object: ' +
+            'omitting it answers 500 about destructuring, and an empty object is not enough — send ' +
+            '{ leftObjectId: null, rightObjectId: null }. Re-parenting through "newParentId" does ' +
+            'apply; the ordering does not.',
+        silentNoOp: 'Re-parenting lands, but sibling order does not change: the call answers success and ' +
+            'every root item keeps the position it had. Public reads do not take item order from ' +
+            'positions either — page items arrive ordered by page id and custom items after them. ' +
+            'There is no body that produces a chosen order today, so build the menu correct in ' +
+            'composition and nesting, tell the human the order is not reproducible, and report it ' +
+            'rather than trying further bodies.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the parent of the item you moved, and the order of its siblings',
+            why: 'the parent change applies while the order does not, and one response covers both',
+        },
+    },
+    AdminMenusController_updateCustomItemPosition: {
+        example: { position: { leftObjectId: null, rightObjectId: null }, newParentId: 12 },
+        note: 'Same body as AdminMenusController_updatePosition: "position" is required and must be an ' +
+            'object — { leftObjectId: null, rightObjectId: null } when the order does not matter.',
+        silentNoOp: 'Re-parenting lands; sibling order does not. See AdminMenusController_updatePosition — ' +
+            'public reads order items by page id rather than by the positions stored here.',
+        verifyWith: {
+            opId: 'AdminMenusController_findOne',
+            check: 'the parent of the item you moved, and the order of its siblings',
+            why: 'the parent change applies while the order does not, and one response covers both',
+        },
+    },
+    AdminFormsController_create: {
+        note: 'Send the payload wrapped under "newForm". The form "type" is missing from the schema but ' +
+            'is accepted and persisted: order | sign_in_up | collection | data | rating. A contact ' +
+            'form is "data". Omit it and the form is created with type null.',
+        verifyWith: {
+            opId: 'AdminFormsController_findAll',
+            check: 'type',
+            why: 'the field is absent from the schema, so an omitted type is not reported as missing',
+        },
+    },
+    AdminFormsController_update: {
+        note: '"formModuleConfigs" is a full replacement list, not a patch. Omitting it deletes every ' +
+            'module binding of the form AND the submissions recorded against those bindings, and the ' +
+            'call still answers 200 true. Read the form first and send its current formModuleConfigs ' +
+            'back unless changing them is the point. This is also the only operation that creates a ' +
+            'binding: an entry with formId, moduleId and either isGlobal or entityIdentifiers. ' +
+            'The rating behaviour of a review form lives in that same entry and has no operation of ' +
+            'its own: isRating, ratingCalculation, maxRatingScale, allowHalfRatings, allowRerating ' +
+            'and isAnonymous. There is no other route to them, which is why they are worth reading ' +
+            'here before asking a human to set them in the panel.',
+        example: {
+            formModuleConfigs: [
+                {
+                    formId: 5,
+                    moduleId: 3,
+                    isGlobal: true,
+                    entityIdentifiers: [],
+                    isRating: true,
+                    ratingCalculation: 'average',
+                    maxRatingScale: 5,
+                    allowHalfRatings: false,
+                    allowRerating: false,
+                    isAnonymous: true,
+                },
+            ],
+        },
+        verifyWith: {
+            opId: 'AdminFormsController_findOne',
+            check: 'formModuleConfigs',
+            why: 'an omitted formModuleConfigs is applied as "unbind everything", submissions included',
+        },
+    },
+    AdminFormDataController_create: {
+        note: 'A submission needs formIdentifier, formModuleConfigId, moduleEntityIdentifier and ' +
+            'locale-keyed formData. formModuleConfigId is the id of a module binding, which only ' +
+            'AdminFormsController_update creates and only AdminFormsController_findOne reports, under ' +
+            'formModuleConfigs[].id — a freshly created form has none and accepts nothing. The server ' +
+            'joins the config back to its form and compares identifiers, so a config id belonging to ' +
+            'another form, or to no form, answers 400 "Incorrect formIdentifier for provided config": ' +
+            'the message names formIdentifier, the wrong field is usually the config id. Checks run ' +
+            'fields first, then the form type, then the config, so a field error arriving first does ' +
+            'not mean the config is optional. A form with type null fails earlier with "Form has ' +
+            'incorrect type". Field validation is wired into the Content API only: through the Admin ' +
+            'API a missing required field is stored rather than rejected, so a submission accepted ' +
+            'here does not prove a visitor\'s submission would pass. A field of type text takes ' +
+            '[{ "htmlValue": "…" }] — a bare string, a list of strings and [{ "value": … }] are all ' +
+            'rejected. On a rating form the score attribute must be marked isRatingValue, or the ' +
+            'form is invalid with "Form must have a rating marker". This route also treats one ' +
+            'authenticated author as one submission per entity, so it rejects the second review of a ' +
+            'product with "You have already rated": a bulk import of visitor reviews cannot go ' +
+            'through the Admin API and has to use the visitor route, which this server does not call.',
+        verifyWith: {
+            opId: 'AdminFormDataController_findByFormMarker',
+            check: 'the submission you sent',
+            why: 'the stored submission is the only proof the binding it names is the intended one',
+        },
+    },
+    AdminPagesController_update: {
+        note: 'Omitting parentId does not leave the parent alone — it moves the page to the root and ' +
+            'decrements the former parent\'s childrenCount. Read the page first and send parentId ' +
+            'back unchanged unless you mean to re-parent it. One field cannot be echoed back at all: ' +
+            'a listing returns "position" as a lexorank string while this operation expects an object ' +
+            'and answers 400 "position must be either object or array" — drop the field from a ' +
+            'read-modify-write body and reorder with the page position operation instead.',
+        verifyWith: {
+            opId: 'AdminPagesController_findOne',
+            check: 'parentId',
+            why: 'an omitted parentId is applied as "move to root", and the update still answers 200',
+        },
+    },
+    AdminEventsController_create: {
+        example: {
+            moduleId: 1,
+            localizeInfos: {
+                en_US: {
+                    title: 'New product published',
+                    subject: 'A new product is live',
+                    template: '<p>{{ product.title }} is now available.</p>',
+                    push: '{{ product.title }} is now available',
+                },
+            },
+        },
+        note: 'The name shown in the events list is localizeInfos.<locale>.title. "name" is what the ' +
+            'create body declares as required, and a name written only there is stored and never ' +
+            'displayed, so send both. The message itself lives in the same locale object — "subject" ' +
+            'for the mail subject, "template" for the mail body, "push" for the push body — and not ' +
+            'under "mailing", which belongs to the mailing module. Placeholders depend on the module: ' +
+            '{{ product.title }} and {{ product.<marker> }} for the catalogue, {{ user.<marker> }} ' +
+            'for the recipient. Events support six modules — catalog, forms, orders, users, payments ' +
+            'and discounts. There is no content module among them, so an event on a page or a block ' +
+            'attribute cannot be built this way; see silentNoOp.',
+        silentNoOp: 'A moduleId outside the six supported modules is accepted: the event is created, reads ' +
+            'back complete, and never fires — the panel draws no settings for it and nothing is ever ' +
+            'sent. Nothing in the response distinguishes it from a working event. If the task needs ' +
+            '"notify when this page changes", say that events do not cover it rather than creating ' +
+            'the object and reporting success.',
+        verifyWith: {
+            opId: 'AdminEventsController_findOne',
+            check: 'moduleId and localizeInfos.<locale>.title',
+            why: 'an event on an unsupported module reads back fully populated and still does nothing',
+        },
+    },
+    AdminEventsController_update: {
+        note: 'The event name, the mail subject and the mail body all live in ' +
+            'localizeInfos.<locale> as "title", "subject" and "template", with "push" for the push ' +
+            'channel. Nothing about the message belongs under "mailing". Supported modules are ' +
+            'catalog, forms, orders, users, payments and discounts; any other moduleId is accepted ' +
+            'and the event never fires.',
+        example: {
+            localizeInfos: {
+                en_US: {
+                    title: 'New product published',
+                    subject: 'A new product is live',
+                    template: '<p>{{ product.title }} is now available.</p>',
+                    push: '{{ product.title }} is now available',
+                },
+            },
+        },
+        verifyWith: {
+            opId: 'AdminEventsController_findOne',
+            check: 'localizeInfos.<locale>.subject and .template',
+            why: 'a subject written under "mailing" is stored there and never used',
+        },
+    },
+    AdminDiscountsController_create: {
+        note: 'A discount with an empty "conditions" and no coupons applies to every order of every ' +
+            'customer, without end. The object is created, the amount is right, and the meaning is ' +
+            'the opposite of "15% off the first order for a subscriber" — a sentence that carries ' +
+            'three limits, none of which is expressed by the amount. State the discount in words, ' +
+            'then check each limit against the body: coupons are the gate (with coupons present, the ' +
+            'conditions apply only when a coupon is used), and conditions narrow which products, ' +
+            'categories or totals are touched. Conditions over attributes work on indexed attributes ' +
+            'only and match nothing, silently, on the rest.',
+        verifyWith: {
+            opId: 'AdminDiscountsController_findOne',
+            check: 'conditions and the coupon list',
+            why: 'a discount meant for some customers cannot have both of them empty',
+        },
+    },
+    AdminDiscountsController_createCoupon: {
+        note: 'A coupon created from a code you supply comes back isReusable: true — one code, valid ' +
+            'for everyone, any number of times. "isReusable" is not accepted in the body, only ' +
+            'reported in the response, so the reuse behaviour follows from WHICH operation created ' +
+            'the coupon. For codes that expire on first use, generate them with ' +
+            'AdminDiscountsController_generateCouponsByMask instead. On a "first order" discount the ' +
+            'difference decides whether one customer gets a discount or everyone does, permanently.',
+        verifyWith: {
+            opId: 'AdminDiscountsController_findOne',
+            check: 'the coupon\'s isReusable',
+            why: 'reuse is not something the create body can set, so the response is the only place it appears',
+        },
+    },
+    AdminDiscountsController_generateCouponsByMask: {
+        note: 'Coupons generated from a mask come back isReusable: false — each code stops working ' +
+            'after the order that used it. That is the only route to single-use codes: a coupon ' +
+            'created from a supplied string is reusable and cannot be changed through the body.',
+    },
+    AdminProductsController_update: {
+        note: 'Always include "blocks" — send [] when there is nothing to set, because omitting it ' +
+            'fails the update. Never include "forms": the schema accepts the field and saving rejects ' +
+            'it. This is also the working route for a product status: send statusId here rather than ' +
+            'through the bulk set-status operation.',
+    },
+    AdminBlocksController_update: {
+        note: 'Omitting blockPages detaches the block from every page it was on. Read the block first ' +
+            'and send its current page list back unless you mean to change it.',
+        verifyWith: {
+            opId: 'AdminBlocksController_findOne',
+            check: 'blockPages',
+            why: 'an omitted blockPages is applied as "detach everything", and the update answers 200',
+        },
+    },
+    AdminProductsController_countAll: { readOnly: true },
+    AdminProductsController_findByIds: {
+        readOnly: true,
+        note: 'The way to verify a batch write without one read per entity: pass every id you wrote and ' +
+            'compare the values in the response. A batch write that reports success can still miss a ' +
+            'single entity, and a per-entity read loop is what makes agents verify a sample instead ' +
+            'of the whole set.',
+    },
+    AdminProductsController_findAllByWithOutCategory: { readOnly: true },
+    AdminProductsController_findAllByCategoryIdForAdmin: { readOnly: true },
+    AdminProductsController_countByCategoryId: { readOnly: true },
+    AdminProductsController_countByCategoryMarker: { readOnly: true },
+    AdminUsersController_findAllByConditions: { readOnly: true },
+    AdminUsersController_search: { readOnly: true },
+    AdminFormDataController_findByFormMarker: { readOnly: true },
+    AdminBlocksController_findCartComplementProductsByBody: { readOnly: true },
+    AdminBlocksController_findCartSimilarProductsByBody: { readOnly: true },
+    AdminBlocksController_findWishlistSimilarProductsByBody: { readOnly: true },
+    AdminUserGroupsController_getGroupRoutesWithPermissions: { readOnly: true },
+};
+export const readOnlyOpIds = () => Object.entries(OPERATION_NOTES)
+    .filter(([, note]) => note.readOnly === true)
+    .map(([opId]) => opId);

package/dist/api/types.d.ts

@@ -1,5 +1,10 @@
 export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 export type RiskLevel = 'read' | 'write' | 'destructive';
+export interface VerifyWith {
+    opId: string;
+    check: string;
+    why: string;
+}
 export interface OperationParam {
     name: string;
     location: 'path' | 'query' | 'header';
@@ -13,6 +18,7 @@ export interface JsonSchema {
     format?: string;
     description?: string;
     example?: unknown;
+    default?: unknown;
     enum?: unknown[];
     items?: JsonSchema;
     properties?: Record<string, JsonSchema>;
@@ -20,6 +26,8 @@ export interface JsonSchema {
     'x-loose'?: boolean;
     'x-source-type'?: string;
     'x-truncated'?: boolean;
+    'x-example-mismatch'?: string;
+    'x-unresolved'?: boolean;
 }
 export interface Operation {
     opId: string;
@@ -38,8 +46,16 @@ export interface Operation {
         required: boolean;
     };
     responseSummary?: string;
+    note?: string;
+    curatedExample?: unknown;
+    verifyWith?: VerifyWith;
+    silentNoOp?: string;
     searchText: string;
 }
+export interface CatalogCoverage {
+    unexposedOpIds: string[];
+    permissionsWithoutOperation: string[];
+}
 export interface Catalog {
     version: 1;
     builtAt: string;
@@ -47,5 +63,6 @@ export interface Catalog {
     swaggerHash: string;
     permissions: string[];
     warnings: string[];
+    coverage: CatalogCoverage;
     operations: Operation[];
 }

package/dist/api/upload.d.ts

@@ -0,0 +1,23 @@
+import type { OperationCatalog } from './catalog.js';
+import type { Operation } from './types.js';
+export interface UploadPayload {
+    bytes: Uint8Array;
+    filename: string;
+    contentType: string;
+}
+export declare class UploadSourceError extends Error {
+}
+export declare const contentTypeOf: (filename: string) => string;
+export declare const resolveUploadOperation: (catalog: OperationCatalog) => Operation | undefined;
+export declare const readLocalUpload: (params: {
+    path: string;
+    root: string;
+    maxBytes: number;
+}) => Promise<UploadPayload>;
+export declare const fetchRemoteUpload: (params: {
+    url: string;
+    allowedHosts: readonly string[];
+    maxBytes: number;
+    timeoutMs: number;
+    filename?: string;
+}) => Promise<UploadPayload>;

package/dist/api/upload.js

@@ -0,0 +1,189 @@
+import { lookup } from 'node:dns/promises';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, extname, isAbsolute, relative, resolve } from 'node:path';
+export class UploadSourceError extends Error {
+}
+const CONTENT_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.zip': 'application/zip',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.txt': 'text/plain',
+};
+export const contentTypeOf = (filename) => CONTENT_TYPES[extname(filename).toLowerCase()] ?? 'application/octet-stream';
+export const resolveUploadOperation = (catalog) => catalog
+    .operations()
+    .find((operation) => operation.method === 'post' && operation.body?.contentType === 'multipart/form-data');
+const asMegabytes = (bytes) => `${(bytes / 1_048_576).toFixed(1)} MB`;
+export const readLocalUpload = async (params) => {
+    const { path, root, maxBytes } = params;
+    const requested = isAbsolute(path) ? path : resolve(root, path);
+    let realRoot;
+    try {
+        realRoot = await realpath(root);
+    }
+    catch {
+        throw new UploadSourceError(`The upload root "${root}" does not exist. Point --upload-root at a directory that holds ` +
+            'the files to upload.');
+    }
+    let real;
+    try {
+        real = await realpath(requested);
+    }
+    catch {
+        throw new UploadSourceError(`No file at "${requested}". Paths are resolved against the upload root "${realRoot}".`);
+    }
+    const inside = relative(realRoot, real);
+    if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) {
+        throw new UploadSourceError(`"${requested}" resolves to "${real}", which is outside the upload root "${realRoot}". ` +
+            'Only files under that root can be uploaded — move the file there or start the server ' +
+            'with a different --upload-root.');
+    }
+    const info = await stat(real);
+    if (!info.isFile()) {
+        throw new UploadSourceError(`"${real}" is not a regular file. Upload one file per call.`);
+    }
+    if (info.size === 0) {
+        throw new UploadSourceError(`"${real}" is empty. An empty upload consumes quota and stores nothing useful.`);
+    }
+    if (info.size > maxBytes) {
+        throw new UploadSourceError(`"${real}" is ${asMegabytes(info.size)}, over the ${asMegabytes(maxBytes)} upload limit. ` +
+            'Raise --upload-max-bytes deliberately or upload a smaller file.');
+    }
+    const filename = basename(real);
+    return { bytes: await readFile(real), filename, contentType: contentTypeOf(filename) };
+};
+const isPrivateAddress = (address, family) => {
+    if (family === 6) {
+        const normalized = address.toLowerCase().split('%')[0] ?? '';
+        if (normalized === '::1' || normalized === '::') {
+            return true;
+        }
+        if (/^f[cd]/.test(normalized) || normalized.startsWith('fe8') || normalized.startsWith('fe9') ||
+            normalized.startsWith('fea') || normalized.startsWith('feb')) {
+            return true;
+        }
+        const dotted = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(normalized);
+        if (dotted?.[1] !== undefined) {
+            return isPrivateAddress(dotted[1], 4);
+        }
+        const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(normalized);
+        if (hex?.[1] !== undefined && hex[2] !== undefined) {
+            const high = Number.parseInt(hex[1], 16);
+            const low = Number.parseInt(hex[2], 16);
+            const octets = [high >> 8, high & 0xff, low >> 8, low & 0xff];
+            return isPrivateAddress(octets.join('.'), 4);
+        }
+        return false;
+    }
+    const parts = address.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part))) {
+        return true;
+    }
+    const [a = 0, b = 0] = parts;
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        a >= 224);
+};
+const assertPublicUrl = async (raw, allowedHosts) => {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new UploadSourceError(`"${raw}" is not a URL. Pass an absolute http or https address.`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new UploadSourceError(`The scheme "${url.protocol}" is not supported. Only http and https addresses are fetched.`);
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (allowedHosts.length > 0 && !allowedHosts.includes(host)) {
+        throw new UploadSourceError(`The host "${host}" is not in the upload allowlist (${allowedHosts.join(', ')}). ` +
+            'Ask the operator to add it with --upload-allowed-hosts.');
+    }
+    const resolved = await lookup(host, { all: true, verbatim: true }).catch(() => {
+        throw new UploadSourceError(`The host "${host}" does not resolve. Check the address.`);
+    });
+    const blocked = resolved.filter((entry) => isPrivateAddress(entry.address, entry.family));
+    if (blocked.length > 0) {
+        throw new UploadSourceError(`The host "${host}" resolves to a private or loopback address (${blocked[0]?.address ?? ''}). ` +
+            'This server does not fetch from the network it runs in — download the file and use ' +
+            'cms_upload_file instead.');
+    }
+    return url;
+};
+const filenameFromUrl = (url, override) => {
+    const fromOverride = override?.trim();
+    if (fromOverride) {
+        return basename(fromOverride);
+    }
+    const last = basename(decodeURIComponent(url.pathname));
+    return last === '' || last === '/' ? 'upload' : last;
+};
+const MAX_REDIRECTS = 3;
+export const fetchRemoteUpload = async (params) => {
+    const { allowedHosts, maxBytes, timeoutMs } = params;
+    let target = await assertPublicUrl(params.url, allowedHosts);
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        let response;
+        try {
+            response = await fetch(target, {
+                redirect: 'manual',
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new UploadSourceError(`Fetching ${target.toString()} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (!location) {
+                throw new UploadSourceError(`${target.toString()} answered ${String(response.status)} with no location header.`);
+            }
+            if (hop === MAX_REDIRECTS) {
+                throw new UploadSourceError(`${params.url} redirects more than ${String(MAX_REDIRECTS)} times. Pass the final address.`);
+            }
+            target = await assertPublicUrl(new URL(location, target).toString(), allowedHosts);
+            continue;
+        }
+        if (!response.ok) {
+            throw new UploadSourceError(`${target.toString()} answered ${String(response.status)}. Nothing was uploaded.`);
+        }
+        const declared = Number(response.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            throw new UploadSourceError(`${target.toString()} declares ${asMegabytes(declared)}, over the ${asMegabytes(maxBytes)} ` +
+                'upload limit. Nothing was downloaded.');
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength === 0) {
+            throw new UploadSourceError(`${target.toString()} returned an empty body.`);
+        }
+        if (bytes.byteLength > maxBytes) {
+            throw new UploadSourceError(`${target.toString()} returned ${asMegabytes(bytes.byteLength)}, over the ` +
+                `${asMegabytes(maxBytes)} upload limit.`);
+        }
+        const filename = filenameFromUrl(target, params.filename);
+        const headerType = (response.headers.get('content-type') ?? '').split(';')[0]?.trim();
+        const contentType = headerType && headerType !== 'application/octet-stream' ? headerType : contentTypeOf(filename);
+        return { bytes, filename, contentType };
+    }
+    throw new UploadSourceError(`${params.url} could not be fetched within ${String(MAX_REDIRECTS)} redirects.`);
+};