@byline/core 6.3.0 → 6.4.0

package/dist/validation/document-fields.js

@@ -0,0 +1,218 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { ERR_VALIDATION, ErrorCodes } from '../lib/errors.js';
+import { fieldToZodSchema } from '../schemas/zod/builder.js';
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+/**
+ * Message for a schema-author callback that threw.
+ *
+ * Deliberately fixed and detail-free. Issue messages cross the server boundary
+ * into the editor, and an unexpected exception can carry internal diagnostics —
+ * a connection string, a file path, an upstream response. Omitting the stack is
+ * not enough, because `error.message` itself is the leak. The real error goes
+ * to `onCallbackError` for server-side logging; a message a validator
+ * deliberately *returns* is authored for the editor and is kept verbatim.
+ */
+const CALLBACK_FAILED = 'could not be validated';
+/**
+ * Validate schema data without transforming or stripping persistence values.
+ *
+ * Never throws. Three things here run schema-author code and can fail on data
+ * they did not anticipate: `validate`, `condition`, and the per-field Zod
+ * schema, whose `validation.rules` may carry a throwing `custom` predicate or a
+ * malformed `pattern` that fails while the schema is being built. A validator
+ * calling `value.trim()` meets a historical version that lacks the field. A raw
+ * exception would abort the walk, discarding the issues already collected, and
+ * escape as an unhandled error rather than a field result.
+ *
+ * Each site is therefore isolated and a failure recorded as an `invalid` issue,
+ * so an ordinary save still refuses the write, and a caller using this for
+ * diagnostics only — restore — is never blocked by it. The editor-facing
+ * message is fixed; the exception goes to `onCallbackError`.
+ */
+export function validateDocumentFields(fields, data, options = {}) {
+    const issues = [];
+    const add = (field, message, kind = 'invalid') => issues.push({ field, message, kind });
+    /**
+     * Report a failed callback. The sink is caller-supplied and reaches a logger,
+     * so it can fail too — a full disk, a transport error. Diagnostics must never
+     * be able to abort the validation they are describing, least of all on the
+     * recovery path whose whole purpose is to not be blocked.
+     */
+    const report = (path, site, error) => {
+        try {
+            options.onCallbackError?.({ path, site, error });
+        }
+        catch {
+            // Nothing left to report it to.
+        }
+    };
+    const visit = (fieldSet, values, prefix = '') => {
+        for (const field of fieldSet) {
+            const path = prefix ? `${prefix}.${field.name}` : field.name;
+            if (options.skip?.(path))
+                continue;
+            // A condition that throws is a misconfiguration: keep the field visible
+            // (fail closed) and surface it, rather than silently hiding the field.
+            if (options.respectConditions && field.condition) {
+                let visible = true;
+                try {
+                    visible = Boolean(field.condition(data, values));
+                }
+                catch (error) {
+                    report(path, 'condition', error);
+                    add(path, `${field.label ?? field.name}: ${CALLBACK_FAILED}`);
+                }
+                if (!visible)
+                    continue;
+            }
+            const value = values[field.name];
+            if (field.localized && options.locale === 'all' && record(value)) {
+                const locales = Object.keys(value);
+                if (!locales.length && !field.optional)
+                    add(path, `${field.label ?? field.name} is required`, 'required');
+                for (const locale of locales)
+                    validate(field, value[locale], `${path}.${locale}`);
+            }
+            else
+                validate(field, value, path);
+        }
+    };
+    const validate = (field, value, path) => {
+        const label = field.label ?? field.name;
+        if (field.validate) {
+            try {
+                // A returned message is authored for the editor: keep it verbatim.
+                const message = field.validate(value, data);
+                if (message)
+                    add(path, message);
+            }
+            catch (error) {
+                report(path, 'validate', error);
+                add(path, `${label}: ${CALLBACK_FAILED}`);
+            }
+        }
+        if (value == null || value === '') {
+            if (!field.optional && field.type !== 'counter')
+                add(path, `${label} is required`, 'required');
+            // Empty values count as absent when checking requiredness.
+            return;
+        }
+        if (field.type === 'group') {
+            if (!record(value))
+                add(path, `${label} must be an object`);
+            else
+                visit(field.fields, value, path);
+        }
+        else if (field.type === 'array' || field.type === 'blocks') {
+            if (!Array.isArray(value))
+                add(path, `${label} must be an array`);
+            else {
+                if (field.type === 'array') {
+                    if (field.validation?.minLength != null && value.length < field.validation.minLength)
+                        add(path, `${label} requires at least ${field.validation.minLength} items`);
+                    if (field.validation?.maxLength != null && value.length > field.validation.maxLength)
+                        add(path, `${label} allows at most ${field.validation.maxLength} items`);
+                }
+                value.forEach((item, index) => {
+                    const itemPath = record(item) && typeof item._id === 'string' && /^[\w-]+$/.test(item._id)
+                        ? `${path}[id=${item._id}]`
+                        : `${path}[${index}]`;
+                    if (!record(item)) {
+                        add(itemPath, 'Item must be an object');
+                        return;
+                    }
+                    if (field.type === 'array')
+                        visit(field.fields, item, itemPath);
+                    else {
+                        const block = field.blocks.find((candidate) => candidate.blockType === item._type);
+                        if (!block)
+                            add(itemPath, 'Unknown block type');
+                        else
+                            visit(block.fields, item, itemPath);
+                    }
+                });
+            }
+        }
+        else {
+            // Both halves are schema-author reachable: `validation.rules` can carry a
+            // `custom` predicate that throws through `refine`, and a malformed
+            // `pattern` throws from `new RegExp` while the schema is still being
+            // built — before any value is parsed.
+            try {
+                const parsed = fieldToZodSchema(field).safeParse(value);
+                if (!parsed.success)
+                    add(path, `${label}: ${parsed.error.issues[0]?.message ?? 'Invalid value'}`);
+            }
+            catch (error) {
+                report(path, 'schema', error);
+                add(path, `${label}: ${CALLBACK_FAILED}`);
+            }
+        }
+    };
+    if (!record(data))
+        return [{ field: '', message: 'Document fields must be an object', kind: 'invalid' }];
+    visit(fields, data);
+    return issues;
+}
+/**
+ * Enforce the collection's declared field contract over prepared content.
+ *
+ * Every versioned write passes through this except a restore, which is exempt
+ * structurally rather than by a parameter here — see `assertWritableContent`
+ * in the lifecycle's `persistence.ts` for why, and for what that exemption
+ * does and does not promise.
+ */
+export function assertDocumentFields(fields, data, locale, logger) {
+    const issues = validateDocumentFields(fields, data, {
+        locale,
+        onCallbackError: logger
+            ? ({ path, site, error }) => logger.error({ err: error, fieldPath: path, site }, 'field validation callback threw')
+            : undefined,
+    });
+    if (issues.length)
+        throw ERR_VALIDATION({
+            message: 'Some document fields are invalid.',
+            details: {
+                reason: 'invalid_document_fields',
+                issues,
+            },
+        });
+}
+/** Accept live errors and serialized reports, discarding all non-contract data. */
+export function getDocumentFieldValidationDetails(error) {
+    try {
+        if (!record(error) || error.code !== ErrorCodes.VALIDATION)
+            return null;
+        const details = error.details;
+        if (!record(details) ||
+            details.reason !== 'invalid_document_fields' ||
+            !Array.isArray(details.issues) ||
+            !details.issues.length)
+            return null;
+        const issues = [];
+        for (const issue of details.issues) {
+            if (!record(issue) ||
+                typeof issue.field !== 'string' ||
+                typeof issue.message !== 'string' ||
+                !issue.message.trim())
+                return null;
+            // An unrecognised or absent `kind` decodes as `invalid` — the blocking
+            // reading. A waiver must never be inferred from a malformed payload.
+            issues.push({
+                field: issue.field,
+                message: issue.message,
+                kind: issue.kind === 'required' ? 'required' : 'invalid',
+            });
+        }
+        return { reason: 'invalid_document_fields', issues };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/validation/document-fields.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/validation/document-fields.test.node.js

@@ -0,0 +1,290 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { ERR_VALIDATION } from '../lib/errors.js';
+import { assertDocumentFields, getDocumentFieldValidationDetails, validateDocumentFields, } from './document-fields.js';
+const fields = [
+    { name: 'title', type: 'text', validation: { minLength: 3 } },
+    { name: 'details', type: 'group', fields: [{ name: 'name', type: 'text' }] },
+    { name: 'items', type: 'array', fields: [{ name: 'name', type: 'text' }] },
+    {
+        name: 'content',
+        type: 'blocks',
+        blocks: [{ blockType: 'heading', fields: [{ name: 'text', type: 'text' }] }],
+    },
+];
+const valid = { title: 'Hello', details: { name: 'OK' }, items: [], content: [] };
+describe('document field validation', () => {
+    it('validates root, group, array and block requirements with stable item paths', () => {
+        const issues = validateDocumentFields(fields, {
+            title: '',
+            details: {},
+            items: [{ _id: 'item-1' }],
+            content: [{ _id: 'block-1', _type: 'heading' }],
+        });
+        expect(issues.map((i) => i.field)).toEqual([
+            'title',
+            'details.name',
+            'items[id=item-1].name',
+            'content[id=block-1].text',
+        ]);
+    });
+    it('accepts valid fields without stripping metadata or changing values', () => {
+        expect(validateDocumentFields(fields, valid)).toEqual([]);
+        expect(valid).toEqual({ title: 'Hello', details: { name: 'OK' }, items: [], content: [] });
+    });
+    it('rejects malformed structures and unknown block types', () => {
+        expect(validateDocumentFields(fields, {
+            ...valid,
+            details: 'wrong',
+            items: [42],
+            content: [{ _type: 'unknown' }],
+        }).map((i) => i.field)).toEqual(['details', 'items[0]', 'content[0]']);
+    });
+    it('enforces declared scalar constraints and relation cardinality', () => {
+        const schema = [
+            { name: 'count', type: 'integer', validation: { min: 1, max: 5 } },
+            { name: 'email', type: 'text', validation: { rules: [{ type: 'email', value: true }] } },
+            {
+                name: 'links',
+                type: 'relation',
+                targetCollection: 'pages',
+                hasMany: true,
+                minItems: 1,
+                maxItems: 2,
+            },
+        ];
+        expect(validateDocumentFields(schema, { count: 7, email: 'bad', links: [] }).map((i) => i.field)).toEqual(['count', 'email', 'links']);
+    });
+    it('accepts JSON and object values and enforces text-area and code rules', () => {
+        const schema = [
+            { name: 'json', type: 'json' },
+            { name: 'object', type: 'object' },
+            { name: 'area', type: 'textArea', validation: { pattern: '^ok' } },
+            { name: 'code', type: 'code', validation: { rules: [{ type: 'min', value: 3 }] } },
+        ];
+        expect(validateDocumentFields(schema, {
+            json: [true, null],
+            object: { count: 1 },
+            area: 'okay',
+            code: 'abc',
+        })).toEqual([]);
+        expect(validateDocumentFields(schema, { json: new Date(), object: [], area: 'bad', code: 'x' }).map((issue) => issue.field)).toEqual(['json', 'object', 'area', 'code']);
+    });
+    it('allows omitted optional containers but validates present children', () => {
+        const schema = [
+            { name: 'details', type: 'group', optional: true, fields: [{ name: 'title', type: 'text' }] },
+        ];
+        expect(validateDocumentFields(schema, {})).toEqual([]);
+        expect(validateDocumentFields(schema, { details: {} })[0]?.field).toBe('details.title');
+    });
+    it('validates locale-all values individually, without assuming an editor JSON shape', () => {
+        const schema = [{ name: 'title', type: 'text', localized: true }];
+        expect(validateDocumentFields(schema, { title: { en: 'Hi', fr: '' } }, { locale: 'all' })[0]?.field).toBe('title.fr');
+        expect(validateDocumentFields(schema, { title: 'Hi' }, { locale: 'en' })).toEqual([]);
+    });
+    it('only exempts condition-hidden fields in the browser precheck', () => {
+        const schema = [{ name: 'hidden', type: 'text', condition: () => false }];
+        expect(validateDocumentFields(schema, {}, { respectConditions: true })).toEqual([]);
+        expect(validateDocumentFields(schema, {})).toHaveLength(1);
+    });
+    it('does not require a client-supplied counter', () => {
+        expect(validateDocumentFields([{ name: 'id', type: 'counter', group: 'ids' }], {})).toEqual([]);
+    });
+    it('decodes only field-validation details and strips private properties', () => {
+        const error = ERR_VALIDATION({
+            message: 'private',
+            details: {
+                reason: 'invalid_document_fields',
+                sql: 'private',
+                issues: [{ field: 'title', message: 'Required', value: 'private' }],
+            },
+        });
+        expect(getDocumentFieldValidationDetails(error)).toEqual({
+            reason: 'invalid_document_fields',
+            issues: [{ field: 'title', message: 'Required', kind: 'invalid' }],
+        });
+        expect(getDocumentFieldValidationDetails({
+            code: error.code,
+            details: { reason: 'missing_document_revision' },
+        })).toBeNull();
+        expect(getDocumentFieldValidationDetails({
+            code: error.code,
+            details: { reason: 'invalid_document_fields', issues: [{ field: 'title' }] },
+        })).toBeNull();
+        expect(getDocumentFieldValidationDetails({
+            get code() {
+                throw new Error('getter');
+            },
+        })).toBeNull();
+    });
+    it('throws a structured validation error', () => {
+        expect(() => assertDocumentFields(fields, {})).toThrow('Some document fields are invalid');
+    });
+    describe('issue classification', () => {
+        it('marks absent declared values required and everything else invalid', () => {
+            const issues = validateDocumentFields(fields, {
+                title: 'ab',
+                details: { name: 'ok' },
+                items: 'not-an-array',
+                content: [{ _id: 'b1', _type: 'unknown' }],
+            });
+            const byField = Object.fromEntries(issues.map((issue) => [issue.field, issue.kind]));
+            expect(byField).toEqual({
+                title: 'invalid',
+                items: 'invalid',
+                'content[id=b1]': 'invalid',
+            });
+            expect(validateDocumentFields(fields, {}).every((issue) => issue.kind === 'required')).toBe(true);
+        });
+        it('classifies a custom validator as invalid even when it describes a requirement', () => {
+            const conditional = [
+                { name: 'kind', type: 'text' },
+                {
+                    name: 'doi',
+                    type: 'text',
+                    optional: true,
+                    validate: (value, data) => data.kind === 'journal' && !value ? 'DOI is required for journal articles' : undefined,
+                },
+            ];
+            const issues = validateDocumentFields(conditional, { kind: 'journal' });
+            expect(issues).toEqual([
+                { field: 'doi', message: 'DOI is required for journal articles', kind: 'invalid' },
+            ]);
+            expect(() => assertDocumentFields(conditional, { kind: 'journal' })).toThrow('Some document fields are invalid');
+            // The condition itself is never consulted by the lifecycle.
+            expect(validateDocumentFields(conditional, { kind: 'blog' })).toEqual([]);
+        });
+    });
+    describe('schema-author callbacks that throw', () => {
+        // A validator written against today's shape meets a historical version
+        // that lacks the field. An exception must not escape the walk.
+        const throwingValidate = [
+            { name: 'title', type: 'text' },
+            {
+                name: 'slug',
+                type: 'text',
+                optional: true,
+                validate: (value) => (value.trim() === '' ? 'empty' : undefined),
+            },
+        ];
+        it('records a failed validator as an issue instead of throwing', () => {
+            const issues = validateDocumentFields(throwingValidate, { title: 'ok' });
+            expect(issues).toEqual([
+                { field: 'slug', message: 'slug: could not be validated', kind: 'invalid' },
+            ]);
+        });
+        it('isolates a throwing custom validation rule', () => {
+            const issues = validateDocumentFields([
+                { name: 'title', type: 'text' },
+                {
+                    name: 'code',
+                    type: 'text',
+                    validation: { rules: [{ type: 'custom', value: (v) => v.deep.thing === 1 }] },
+                },
+            ], { title: 't', code: 'x' });
+            expect(issues).toEqual([
+                { field: 'code', message: 'code: could not be validated', kind: 'invalid' },
+            ]);
+        });
+        it('isolates a failure while the schema itself is being built', () => {
+            // A malformed `pattern` throws from `new RegExp` before any parse.
+            const issues = validateDocumentFields([{ name: 'p', type: 'text', validation: { rules: [{ type: 'pattern', value: '([' }] } }], { p: 'x' });
+            expect(issues).toEqual([
+                { field: 'p', message: 'p: could not be validated', kind: 'invalid' },
+            ]);
+        });
+        it('keeps collecting issues after one callback fails', () => {
+            const issues = validateDocumentFields(throwingValidate, {});
+            expect(issues.map((issue) => issue.field)).toEqual(['title', 'slug']);
+        });
+        it('still refuses an ordinary save, with a readable message', () => {
+            expect(() => assertDocumentFields(throwingValidate, { title: 'ok' })).toThrow('Some document fields are invalid');
+        });
+        it('treats a throwing condition as visible and surfaces it', () => {
+            const throwingCondition = [
+                { name: 'a', type: 'text', condition: (data) => data.missing.deep === 1 },
+            ];
+            const issues = validateDocumentFields(throwingCondition, {}, { respectConditions: true });
+            // Fail closed: the field is still validated, and the misconfiguration
+            // is reported rather than silently hiding the field.
+            expect(issues.map((issue) => issue.message)).toEqual([
+                'a: could not be validated',
+                'a is required',
+            ]);
+        });
+        it('never copies an exception message into an editor-facing issue', () => {
+            // Issue messages cross the server boundary. An unexpected exception can
+            // carry internal diagnostics, so the message is fixed and detail-free.
+            const secret = 'ECONNREFUSED postgres://user:hunter2@10.0.0.4:5432/prod';
+            const seen = [];
+            const issues = validateDocumentFields([
+                {
+                    name: 'x',
+                    type: 'text',
+                    validate: () => {
+                        throw new Error(secret);
+                    },
+                },
+            ], { x: 'v' }, { onCallbackError: ({ error, site }) => seen.push([site, error]) });
+            expect(issues).toEqual([
+                { field: 'x', message: 'x: could not be validated', kind: 'invalid' },
+            ]);
+            expect(JSON.stringify(issues)).not.toContain('hunter2');
+            // The real error is still available to server-side diagnostics.
+            expect(seen).toEqual([['validate', expect.objectContaining({ message: secret })]]);
+        });
+        it('is not aborted by a diagnostic sink that throws', () => {
+            // The sink reaches a logger, which can fail too. Diagnostics must never
+            // abort the validation they describe.
+            const issues = validateDocumentFields([
+                {
+                    name: 'x',
+                    type: 'text',
+                    validate: () => {
+                        throw new Error('inner');
+                    },
+                },
+            ], { x: 'v' }, {
+                onCallbackError: () => {
+                    throw new Error('logger is down');
+                },
+            });
+            expect(issues).toEqual([
+                { field: 'x', message: 'x: could not be validated', kind: 'invalid' },
+            ]);
+        });
+        it('keeps a message a validator deliberately returns', () => {
+            const issues = validateDocumentFields([
+                {
+                    name: 'doi',
+                    type: 'text',
+                    optional: true,
+                    validate: () => 'DOI must be a 10.x prefix',
+                },
+            ], { doi: 'x' });
+            expect(issues[0]?.message).toBe('DOI must be a 10.x prefix');
+        });
+    });
+    describe('the serialized decoder', () => {
+        it('decodes an unknown or absent kind as invalid, never as waivable', () => {
+            const details = getDocumentFieldValidationDetails({
+                code: ERR_VALIDATION({ message: 'x' }).code,
+                details: {
+                    reason: 'invalid_document_fields',
+                    issues: [
+                        { field: 'a', message: 'A' },
+                        { field: 'b', message: 'B', kind: 'bogus' },
+                        { field: 'c', message: 'C', kind: 'required' },
+                    ],
+                },
+            });
+            expect(details?.issues.map((issue) => issue.kind)).toEqual(['invalid', 'invalid', 'required']);
+        });
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -86,19 +86,19 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.4",
     "uuid": "^14.0.2",
-    "zod": "^4.6.2",
-    "@byline/auth": "6.3.0"
+    "zod": "^4.6.5",
+    "@byline/auth": "6.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.13",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "npm-run-all": "^4.1.5",
-    "tsc-alias": "^1.9.4",
+    "tsc-alias": "^1.9.5",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public",