bank20baht-validator 0.4.2 → 0.5.0

package/README.md

@@ -46,7 +46,7 @@ POST /api/submissions {"id":"todo-form","data":{"title":"ab"}}
 
 ## Compatibility
 
-Peers on `bank20baht-ui` **>=0.11 <0.12** (the engine and the `FieldType` union come from there; see `peerDependencies`). In a workspace that also builds `bank20baht-ui`, keep the peer range in
+Peers on `bank20baht-ui` **>=0.13 <0.14** (the engine and the `FieldType` union come from there; see `peerDependencies`). In a workspace that also builds `bank20baht-ui`, keep the peer range in
 step with the core version or the validator's `tsc` build resolves a stale copy from npm.
 
 ## What it enforces
@@ -54,16 +54,20 @@ step with the core version or the validator's `tsc` build resolves a stale copy
 - Every declarative validator of the field descriptors: `required`, `min_length`, `max_length`, `min`, `max`, `pattern`, `email`, and `custom` (via a `Registry`).
 - Value **shape** per field type before any validator runs — a `password`/`text` must be a string, a `number` a finite number, a `dropdown` one of its option keys — so `{"$gt":""}` from a raw API call is rejected, not treated as "non-empty".
 - **Workflow rules first** (`evaluate` from `bank20baht-ui/engine`): fields hidden by rules are excluded and smuggled values are cleared; `required` derived from rules is enforced; `setValue` results are computed.
-- Approval steps: a `decision` must be present, and the comment policy (`required` / `requireOnReject`) is honored.
+- Approval steps: a `decision` must be present, the comment must be a string, and the comment policy (`required` / `requireOnReject`) is honored (a blank or zero-width comment does not count).
+- **Canonical data holds only what the UI could emit:** repeater rows keep their declared columns only (a row with its own `__proto__` key is rejected), file values must be uploaded refs `{ name, size, url, type? }` with an `http(s)` or relative `url` and keep only those keys, `-0` is stored as `0`.
+- **Strict by default (0.5.0):** a `custom` validator or `submit` script with no own entry in the registry, and a script that throws, are issues instead of being skipped. Pass `{ strict: false }` as the fifth argument to get the client's warn-and-skip behaviour (previews, docs tooling).
 - **Client `submit` scripts** (spec 01 §14): re-run headlessly with the same `registry.scripts` — `g.setValue()` lands in canonical data, `g.addErrorMessage()` becomes an issue on `$` (`form_name.$` in a workflow), returning `false` blocks. `load` / `change` scripts are UI-only and never run here, so a field a client script hides is still validated: keep submit-relevant logic in rules or validators. `parseSchema` rejects a `scripts[]` entry with an unknown `on`, no `handler`, or a `change` hook on a field that does not exist.
 
 ## API
 
 | export | what it does |
 | --- | --- |
-| `validateSubmission(schema, data, registry?)` | dispatches on schema kind — the single server entry point |
-| `validateFormData(form, data, registry?)` | mirrors `<baht-form>.validate()` for a standalone form |
-| `validateWorkflowData(workflow, data, registry?)` | evaluates rules, then validates every visible form |
+| `validateSubmission(schema, data, registry?, locale?, options?)` | dispatches on schema kind — the single server entry point |
+| `validateFormData(form, data, registry?, locale?, options?)` | mirrors `<baht-form>.validate()` for a standalone form |
+| `validateWorkflowData(workflow, data, registry?, locale?, options?)` | evaluates rules, then validates every visible form |
+
+`options` is `{ strict?: boolean }` (default `true`, see above).
 | `parseSchema(json)` | structural gate for storing builder output (throws on bad input) |
 | `isFormDefinition` / `isWorkflowDefinition` | schema kind guards |
 

package/dist/index.d.ts

@@ -5,6 +5,15 @@ export interface ValidationIssue {
     ref: string;
     message: string;
 }
+/**
+ * `strict` (default true) fails closed on anything the server cannot check:
+ * a `custom` validator or a `submit` script with no registry entry, and a
+ * script that throws, each become an issue. `strict: false` restores the
+ * client's warn-and-skip behaviour for callers that only preview.
+ */
+export interface ValidateOptions {
+    strict?: boolean;
+}
 export interface ValidationResult {
     valid: boolean;
     issues: ValidationIssue[];
@@ -24,7 +33,7 @@ export declare function isFormDefinition(schema: unknown): schema is FormDefinit
  * views are client-side display only, the server always validates the full
  * form (a view can never weaken a validation rule).
  */
-export declare function validateFormData(form: FormDefinition, input: unknown, registry?: Registry, locale?: Locale): ValidationResult;
+export declare function validateFormData(form: FormDefinition, input: unknown, registry?: Registry, locale?: Locale, options?: ValidateOptions): ValidationResult;
 /**
  * Validate a whole workflow submission — mirrors what `<baht-workflow>`
  * enforces across its steps: rules are evaluated first (`evaluate`), invisible
@@ -34,7 +43,7 @@ export declare function validateFormData(form: FormDefinition, input: unknown, r
  * client fires `baht-complete { status: 'rejected' }` immediately, so later
  * forms are never visited.
  */
-export declare function validateWorkflowData(workflow: WorkflowDefinition, input: unknown, registry?: Registry, locale?: Locale): ValidationResult;
+export declare function validateWorkflowData(workflow: WorkflowDefinition, input: unknown, registry?: Registry, locale?: Locale, options?: ValidateOptions): ValidationResult;
 /**
  * Validate a submission body's `data` against whichever schema kind `id`
  * resolved to. This is the single server entry point:
@@ -42,7 +51,7 @@ export declare function validateWorkflowData(workflow: WorkflowDefinition, input
  *   const schema = store.get(body.id);
  *   const result = validateSubmission(schema, body.data);
  */
-export declare function validateSubmission(schema: SchemaDefinition, data: unknown, registry?: Registry, locale?: Locale): ValidationResult;
+export declare function validateSubmission(schema: SchemaDefinition, data: unknown, registry?: Registry, locale?: Locale, options?: ValidateOptions): ValidationResult;
 /**
  * Structural gate for storing builder output — the same checks the builder's
  * Import applies, so the server only ever stores schemas the client could

package/dist/index.js

@@ -13,7 +13,7 @@
 // every value must have the shape the UI control could actually emit before
 // the authored validators run.
 // ---------------------------------------------------------------------------
-import { applyFlags, approvalFields, conditionRowRefs, createScriptContext, defaultValue, evaluate, hasScripts, runScripts, getCatalog, normalizeTagsValue, parseDisabledEntry, parseIsoDate, parseIsoDateTime, parseRowRef, resolveViewFields, setCatalog, setLocale, t, validateField, walkPath, normalizeLegacySchema, } from 'bank20baht-ui/engine';
+import { applyFlags, approvalFields, conditionRowRefs, createScriptContext, defaultValue, evaluate, hasScripts, runScripts, getCatalog, normalizeTagsValue, parseDisabledEntry, parseIsoDate, parseIsoDateTime, parseRowRef, resolveViewFields, setCatalog, setLocale, t, isBlank, isSafeUrl, isUnsafePattern, validateField, walkPath, normalizeLegacySchema, } from 'bank20baht-ui/engine';
 /**
  * Run `fn` with the catalog switched to `locale`, restoring the previous
  * catalog after. The engine catalog is module-global; validation is fully
@@ -127,10 +127,24 @@ function tagsShapeIssue(field, value, optionKeys) {
     }
     return null;
 }
+/** The serializable ref an uploader returns (spec 01 §13), with a link-safe url. */
+function isUploadedFile(v) {
+    return (isRecord(v) &&
+        typeof v.name === 'string' &&
+        typeof v.size === 'number' &&
+        Number.isFinite(v.size) &&
+        v.size >= 0 &&
+        typeof v.url === 'string' &&
+        isSafeUrl(v.url) &&
+        (v.type === undefined || typeof v.type === 'string'));
+}
+function canonicalRef({ name, size, url, type }) {
+    return type === undefined ? { name, size, url } : { name, size, url, type };
+}
 function fileIssue(field, value) {
     if (field.multiple)
-        return shapeMessage(Array.isArray(value) && value.every(isRecord));
-    return shapeMessage(isRecord(value));
+        return shapeMessage(Array.isArray(value) && value.every(isUploadedFile));
+    return shapeMessage(isUploadedFile(value));
 }
 function typeIssue(field, value) {
     if (value === null || value === undefined)
@@ -179,6 +193,10 @@ function shapeIssues(field, value, ref) {
                 issues.push({ ref: `${ref}[${i}]`, message: t('pattern') });
                 return;
             }
+            if (Object.hasOwn(row, '__proto__')) {
+                issues.push({ ref: `${ref}[${i}]`, message: t('pattern') });
+                return;
+            }
             for (const sub of field.fields ?? []) {
                 if (sub.type === 'label' || UNSAFE_KEYS.has(sub.key))
                     continue;
@@ -199,8 +217,66 @@ function shapeIssues(field, value, ref) {
  * views are client-side display only, the server always validates the full
  * form (a view can never weaken a validation rule).
  */
-export function validateFormData(form, input, registry, locale) {
-    return withLocale(locale, () => formDataResult(form, input, registry));
+export function validateFormData(form, input, registry, locale, options) {
+    const reg = serverRegistry([form], registry, options);
+    return withLocale(locale, () => formDataResult(form, input, reg));
+}
+function ownEntry(map, name) {
+    return map && Object.hasOwn(map, name) ? map[name] : undefined;
+}
+function guardedScript(name, handler) {
+    return (g, detail) => {
+        try {
+            return handler(g, detail);
+        }
+        catch (err) {
+            console.error(`[bank20baht-validator] submit script "${name}" threw`, err);
+            g.addErrorMessage(`submit script "${name}" failed`);
+            return false;
+        }
+    };
+}
+/**
+ * The registry the engine sees. In strict mode every `custom` validator and
+ * `submit` script the schema names resolves to something that fails closed:
+ * the caller's own entry (scripts wrapped so a throw is an issue), else a stub
+ * that reports the missing name. Own entries only, so `toString` never
+ * resolves through Object.prototype.
+ */
+function serverRegistry(forms, registry, options) {
+    if (options?.strict === false)
+        return registry;
+    const validators = new Map();
+    const scripts = new Map();
+    for (const form of forms) {
+        const fields = form.fields.flatMap((f) => [
+            f,
+            ...(f.type === 'repeater' ? (f.fields ?? []) : []),
+        ]);
+        for (const spec of fields.flatMap((f) => f.validators ?? [])) {
+            if (spec.type !== 'custom')
+                continue;
+            const name = spec.fn ?? '';
+            validators.set(name, ownEntry(registry?.validators, name) ?? (() => `unknown custom validator "${name}"`));
+        }
+        for (const spec of form.scripts ?? []) {
+            if (spec.on !== 'submit')
+                continue;
+            const name = spec.handler;
+            const handler = ownEntry(registry?.scripts, name);
+            scripts.set(name, handler
+                ? guardedScript(name, handler)
+                : (g) => {
+                    g.addErrorMessage(`submit script "${name}" is not registered`);
+                    return false;
+                });
+        }
+    }
+    return {
+        ...registry,
+        validators: Object.fromEntries(validators),
+        scripts: Object.fromEntries(scripts),
+    };
 }
 /**
  * A tags value as the client emits it: trimmed, case-insensitive deduped
@@ -219,30 +295,39 @@ function canonicalTags(field, v) {
     return normalizeTagsValue(v, field.options_from ? undefined : field.options);
 }
 /**
- * Canonical value for one field: `tags` via `canonicalTags` (the same
- * transform `validateField` applies internally when checking it, applied
- * here too so the persisted `data` matches byte-for-byte); `repeater`
- * recurses one row deep to normalise any `tags` COLUMN the same way (a
- * repeater never nests, spec 01 §10). Every other type passes through.
- * Only own keys are ever assigned, so a `__proto__` key stays a plain
- * data property.
+ * Canonical value for one field, as the client would emit it: `tags` via
+ * `canonicalTags` (the transform `validateField` applies internally, so the
+ * persisted `data` matches byte-for-byte); a file ref keeps only its ref
+ * fields; `-0` becomes `0`; a repeater row is rebuilt from its declared
+ * columns only (a repeater never nests, spec 01 §10). Every other value
+ * passes through. Runs after `shapeIssues`, or on rule input where a
+ * wrong-shaped value is left for `shapeIssues` to reject.
  */
 function normalizeCanonicalValue(field, raw) {
     if (field.type === 'tags')
         return canonicalTags(field, raw);
-    if (field.type !== 'repeater' || !Array.isArray(raw))
-        return raw;
-    return raw.map((row) => {
-        if (!isRecord(row))
-            return row;
-        const next = { ...row };
-        for (const sub of field.fields ?? []) {
-            if (sub.type === 'tags' && Object.hasOwn(next, sub.key)) {
-                next[sub.key] = canonicalTags(sub, next[sub.key]);
-            }
-        }
-        return next;
-    });
+    if (field.type === 'number' || field.type === 'currency')
+        return Object.is(raw, -0) ? 0 : raw;
+    if (field.type === 'file') {
+        if (isUploadedFile(raw))
+            return canonicalRef(raw);
+        return Array.isArray(raw) && raw.every(isUploadedFile) ? raw.map(canonicalRef) : raw;
+    }
+    if (field.type === 'repeater' && Array.isArray(raw)) {
+        return raw.map((row) => canonicalRow(field, row));
+    }
+    return raw;
+}
+function canonicalRow(field, row) {
+    if (!isRecord(row))
+        return row;
+    const next = {};
+    for (const sub of field.fields ?? []) {
+        if (sub.type === 'label' || UNSAFE_KEYS.has(sub.key) || !Object.hasOwn(row, sub.key))
+            continue;
+        next[sub.key] = normalizeCanonicalValue(sub, row[sub.key]);
+    }
+    return next;
 }
 /**
  * Copy of the workflow input with every tags value (and tags column)
@@ -362,8 +447,9 @@ function submitScriptIssues(form, data, registry, refPrefix = '') {
  * client fires `baht-complete { status: 'rejected' }` immediately, so later
  * forms are never visited.
  */
-export function validateWorkflowData(workflow, input, registry, locale) {
-    return withLocale(locale, () => workflowDataResult(workflow, input, registry));
+export function validateWorkflowData(workflow, input, registry, locale, options) {
+    const reg = serverRegistry(workflow.forms, registry, options);
+    return withLocale(locale, () => workflowDataResult(workflow, input, reg));
 }
 /** Early-out for input that is not `{ formName: {…} }`, else null. */
 function workflowInputRejection(input) {
@@ -439,7 +525,7 @@ function rowStatesOf(form, field, derived) {
 }
 function formFieldIssues(form, derived, registry) {
     const issues = [];
-    for (const field of sorted(form.fields)) {
+    for (const field of sorted([...form.fields, ...approvalFields(form)])) {
         if (field.type === 'label')
             continue;
         issues.push(...workflowFieldIssues(form, field, derived, registry));
@@ -479,11 +565,11 @@ function workflowDataResult(workflow, input, registry) {
         .map((e) => ({ ref: e.ref, message: e.message }));
     const pathList = pruneOffPath(workflow, derived);
     for (const form of visitedForms(workflow, derived, pathList)) {
+        issues.push(...formFieldIssues(form, derived, registry));
         if (form.kind === 'approval') {
             issues.push(...approvalIssues(form, derived.data));
             continue;
         }
-        issues.push(...formFieldIssues(form, derived, registry));
         if (hasScripts(form, 'submit')) {
             const formData = (derived.data[form.form_name] ??= {});
             issues.push(...submitScriptIssues(form, formData, registry, `${form.form_name}.`));
@@ -501,8 +587,9 @@ function approvalIssues(form, data) {
     }
     const mode = form.approval?.comment ?? 'optional';
     const commentRequired = mode === 'required' || (mode === 'requireOnReject' && decision === 'rejected');
-    // eslint-disable-next-line @typescript-eslint/no-base-to-string -- mirrors <baht-workflow>.decide(): String(comment ?? '') on an untrusted value
-    if (commentRequired && String(values.comment ?? '').trim() === '') {
+    // the comment's shape was already checked; a wrong shape was reset to null
+    const comment = typeof values.comment === 'string' ? values.comment : '';
+    if (commentRequired && isBlank(comment)) {
         issues.push({ ref: `${form.form_name}.comment`, message: t('commentRequired') });
     }
     return issues;
@@ -514,11 +601,12 @@ function approvalIssues(form, data) {
  *   const schema = store.get(body.id);
  *   const result = validateSubmission(schema, body.data);
  */
-export function validateSubmission(schema, data, registry, locale) {
-    if (isWorkflowDefinition(schema))
-        return validateWorkflowData(schema, data, registry, locale);
+export function validateSubmission(schema, data, registry, locale, options) {
+    if (isWorkflowDefinition(schema)) {
+        return validateWorkflowData(schema, data, registry, locale, options);
+    }
     if (isFormDefinition(schema))
-        return validateFormData(schema, data, registry, locale);
+        return validateFormData(schema, data, registry, locale, options);
     return {
         valid: false,
         issues: [{ ref: '$', message: 'unrecognized schema: neither a form nor a workflow' }],
@@ -684,25 +772,6 @@ function assertValidFields(form) {
         assertSubFields(field, form.form_name);
     }
 }
-/**
- * True for the textbook ReDoS shape: an unbounded quantifier (`* + {n,}`)
- * applied to a group whose ENTIRE body is one unboundedly-quantified atom —
- * `(a+)+`, `(\d*)*`, `(?:\w+){2,}`. That exact nesting is always either
- * redundant (matches the same language as a single quantifier) or exponential
- * to backtrack, so rejecting it has no legitimate false positives. It is
- * deliberately NARROW: longer bodies like `(abc+)+` are safe (the literal
- * prefix removes the cross-iteration ambiguity) and other catastrophic shapes
- * (e.g. overlapping alternation `(a|a)*`) are out of scope — patterns are
- * builder-authored, so the goal is catching the classic authoring mistake at
- * save time, not sandboxing hostile regexes.
- */
-function hasNestedUnboundedQuantifier(pattern) {
-    // Strip escaped chars and character classes first so `\+`, `[+]` etc.
-    // aren't mistaken for quantifiers or group delimiters.
-    const stripped = pattern.replace(/\\./g, 'x').replace(/\[[^\]]*\]/g, 'C');
-    const unbounded = '(?:[*+]|\\{\\d+,\\})';
-    return new RegExp(`\\((?:\\?:)?[^()|]${unbounded}\\??\\)${unbounded}`).test(stripped);
-}
 function assertFieldKey(field, form_name) {
     // labels are static blocks and may omit the key; everything else needs one
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard: value is untrusted JSON
@@ -725,10 +794,10 @@ function assertPatternValidator(v, where) {
     catch {
         throw new Error(`invalid pattern ${JSON.stringify(v.value)} on ${where}`);
     }
-    if (hasNestedUnboundedQuantifier(pattern)) {
-        throw new Error(`pattern on ${where} nests unbounded quantifiers ` +
-            `(e.g. "(a+)+") — this backtracks catastrophically on hostile input; ` +
-            `an equivalent single quantifier matches the same strings`);
+    if (isUnsafePattern(pattern)) {
+        throw new Error(`pattern on ${where} nests or overlaps unbounded quantifiers ` +
+            `(e.g. "(a+)+", "(\\w|\\d)+") — this backtracks catastrophically on hostile input; ` +
+            `rewrite it so each character can match only one way`);
     }
 }
 function assertFieldValidators(field, form_name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bank20baht-validator",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "Runtime validation for bahtui form/workflow JSON \u2014 the exact engine rules the client runs, on the server.",
   "license": "MIT",
@@ -41,12 +41,12 @@
     "test:coverage": "vitest run --coverage"
   },
   "devDependencies": {
-    "bank20baht-ui": "^0.12.0",
+    "bank20baht-ui": "^0.13.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "bank20baht-ui": ">=0.12.1 <0.13.0"
+    "bank20baht-ui": ">=0.13.0 <0.14.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",