@jini-ai/cms 0.5.5 → 0.5.6

package/dist/forms/descriptor-rules.js

@@ -0,0 +1,112 @@
+import { FIELD_TYPE_REGISTRY, isBrowserSafeFieldPattern, isSafeFieldPattern, MAX_FORM_FILE_BYTES, resolveFormField, SAFE_FORM_FILE_TYPES } from "./field-registry.js";
+const KEYS = new Set(["id", "name", "label", "type", "required", "placeholder", "helpText", "default", "options", "minLength", "maxLength", "pattern", "min", "max", "step", "accept", "maxFileSize", "checkboxValue", "className", "attributes"]);
+const TEMPORAL = new Set(["date", "time", "datetime"]);
+const fail = (field, reason) => ({ field, reason });
+/** Text rules apply to explicit descriptor properties and their legacy attributes alike. */
+function textConstraints(field) {
+    const errors = [];
+    const kind = FIELD_TYPE_REGISTRY[field.type];
+    const minLength = field.minLength ?? (field.attributes?.minlength !== undefined ? Number(field.attributes.minlength) : undefined);
+    const pattern = field.pattern ?? field.attributes?.pattern;
+    if (minLength !== undefined && (!kind?.textual || !Number.isInteger(minLength) || minLength < 0 || minLength > (field.maxLength ?? 5000)))
+        errors.push("minLength must be an integer within the text length bounds");
+    if (field.type !== "checkbox" && field.maxLength != null && (!kind?.textual || !Number.isInteger(field.maxLength)))
+        errors.push("maxLength is only supported on text fields and must be an integer");
+    if (pattern !== undefined && (!kind?.textual || typeof pattern !== "string" || !isSafeFieldPattern({ pattern })))
+        errors.push("pattern must be a safe text pattern (no groups, alternation, backreferences or multiple repetitions)");
+    else if (typeof pattern === "string" && !isBrowserSafeFieldPattern({ pattern }))
+        errors.push("pattern is ignored by browsers: escape '-' and other symbols inside [...] with a backslash, e.g. [0-9 +.\\-]");
+    return errors;
+}
+/** Choice options are bounded, unique and non-empty; scalar/array defaults use the same validator. */
+function choiceConstraints(field) {
+    const kind = FIELD_TYPE_REGISTRY[field.type];
+    if (!kind?.choices)
+        return field.options === undefined ? [] : ["options are only supported on choice fields"];
+    if (!Array.isArray(field.options) || field.options.length === 0 || field.options.length > 100)
+        return ["choice fields require 1-100 options"];
+    const values = new Set();
+    const errors = [];
+    for (const option of field.options) {
+        if (!option || typeof option.value !== "string" || option.value.length === 0 || option.value.length > 200 || typeof option.label !== "string" || option.label.length === 0 || option.label.length > 200 || Object.keys(option).some((key) => key !== "value" && key !== "label")) {
+            errors.push("options must contain only a non-empty value and label (up to 200 characters)");
+            continue;
+        }
+        if (values.has(option.value))
+            errors.push("option values must be unique");
+        values.add(option.value);
+    }
+    return errors;
+}
+/** Numeric/date bounds must use native formats; reversed intervals and non-positive steps fail. */
+function boundConstraints(field) {
+    const errors = [];
+    const numeric = field.type === "number" || field.type === "range";
+    const temporal = TEMPORAL.has(field.type);
+    for (const key of ["min", "max"]) {
+        const value = field[key] ?? field.attributes?.[key];
+        if (value === undefined)
+            continue;
+        if (numeric) {
+            if (typeof value !== "number" && (typeof value !== "string" || value.trim() === ""))
+                errors.push(`${key} must be a finite number`);
+            else if (!Number.isFinite(Number(value)))
+                errors.push(`${key} must be a finite number`);
+        }
+        else if (temporal) {
+            if (typeof value !== "string" || resolveFormField({ field: { id: "bound", label: "Bound", type: field.type, required: true }, value }).kind !== "accepted")
+                errors.push(`${key} must match the field's native date/time format`);
+        }
+        else
+            errors.push(`${key} is only supported on numeric and date/time fields`);
+    }
+    const min = field.min ?? field.attributes?.min;
+    const max = field.max ?? field.attributes?.max;
+    if (min !== undefined && max !== undefined) {
+        // Reuse the submission bound validator so equivalent local-time spellings stay equivalent.
+        const comparison = temporal ? resolveFormField({ field: { id: "bound", label: "Bound", type: field.type, required: true, min }, value: max }) : undefined;
+        if (numeric ? Number(min) > Number(max) : comparison?.kind === "rejected" && comparison.reason === "below_min")
+            errors.push("min must not exceed max");
+    }
+    const step = field.step ?? (field.attributes?.step !== undefined ? Number(field.attributes.step) : undefined);
+    if (step !== undefined && (!numeric || !Number.isFinite(step) || step <= 0))
+        errors.push("step must be a positive finite number on a numeric field");
+    return errors;
+}
+/** File fields may narrow the safe list/size, and cannot synthesize a default upload. */
+function fileConstraints(field) {
+    if (field.type !== "file")
+        return field.accept !== undefined || field.maxFileSize !== undefined ? ["accept/maxFileSize are only supported on file fields"] : [];
+    const errors = [];
+    if (field.maxFileSize !== undefined && (!Number.isInteger(field.maxFileSize) || field.maxFileSize < 1 || field.maxFileSize > MAX_FORM_FILE_BYTES))
+        errors.push(`maxFileSize must be 1-${MAX_FORM_FILE_BYTES} bytes`);
+    if (field.accept !== undefined && (!Array.isArray(field.accept) || field.accept.length === 0 || field.accept.length > 20 || field.accept.some((mime) => !Object.hasOwn(SAFE_FORM_FILE_TYPES, mime) && !["image/*", "video/*", "*/*"].includes(mime))))
+        errors.push("accept must contain recognized safe MIME types or image/*, video/*, */*");
+    if (field.default !== undefined)
+        errors.push("file fields cannot have defaults");
+    return errors;
+}
+/** Collect definition errors without coercing an untrusted descriptor into a valid one.
+ * @complexity O(k + o) for descriptor keys and at most 100 options. */
+export function commonDescriptorErrors({ field }, _optional = {}) {
+    const errors = [];
+    for (const key of Object.keys(field))
+        if (!KEYS.has(key))
+            errors.push(`property '${key}' is not allowed`);
+    if (typeof field.required !== "boolean")
+        errors.push("required must be a boolean");
+    if (field.name !== undefined && field.name !== field.id)
+        errors.push("name must equal the stable field id");
+    for (const key of ["placeholder", "helpText"])
+        if (field[key] !== undefined && (typeof field[key] !== "string" || field[key].length > 500))
+            errors.push(`${key} must be a string of at most 500 characters`);
+    if (Object.hasOwn(FIELD_TYPE_REGISTRY, field.type))
+        errors.push(...textConstraints(field), ...choiceConstraints(field), ...boundConstraints(field), ...fileConstraints(field));
+    if (field.default !== undefined && field.type !== "file" && errors.length === 0) {
+        const result = resolveFormField({ field: { ...field, required: false }, value: field.default });
+        if (result.kind === "rejected")
+            errors.push(`default: ${result.reason}`);
+    }
+    return errors.map((reason) => fail(field.id || "(unknown)", reason));
+}
+//# sourceMappingURL=descriptor-rules.js.map

package/dist/forms/email-format.d.ts

@@ -0,0 +1,7 @@
+/** Returns whether the entire value matches native single-address email syntax.
+ * JS's $ can match before a final newline; checking the full match refuses that bypass.
+ * @complexity O(n) in the address length, bounded by the caller's 5000-character text cap. */
+export declare function isValidFormEmail({ value }: {
+    value: string;
+}, _optional?: {}): boolean;
+//# sourceMappingURL=email-format.d.ts.map

package/dist/forms/email-format.js

@@ -0,0 +1,11 @@
+/** Native email syntax shared by the registry and the compatibility submission guard. */
+// Match native type=email syntax (WHATWG HTML email state), including single-label domains.
+// Do not trim or rewrite answers: Jini's payload contract preserves submitted strings.
+const EMAIL_PATTERN = /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+/** Returns whether the entire value matches native single-address email syntax.
+ * JS's $ can match before a final newline; checking the full match refuses that bypass.
+ * @complexity O(n) in the address length, bounded by the caller's 5000-character text cap. */
+export function isValidFormEmail({ value }, _optional = {}) {
+    return EMAIL_PATTERN.exec(value)?.[0] === value;
+}
+//# sourceMappingURL=email-format.js.map

package/dist/forms/express/handler.js

@@ -22,15 +22,11 @@ import { FormDefinitionNotFoundError, FormRateLimitExceededError, FormSubmission
  * wiped (2026-08-31 fix) — see `http/site/form-render.ts`'s "Validation flash cookie" section for why
  * this travels via a cookie rather than the query string.
  */
-const MAX_BODY_STRING_LENGTH = 5000;
-/** Truncates string values in an untrusted body before it reaches `submitForm`; other types pass through unchanged so `validateSubmissionPayload` can reject them by type, mirroring `analytics-ingest.ts`'s `parseBeacon`. */
+/** Leave values intact so the server validator rejects oversize input instead of silently
+ * accepting truncated answers. The transport's JSON/urlencoded/multipart parsers bound memory.
+ * Unknown keys and duplicate scalar controls remain visible to the domain validator. */
 function boundBody(body) {
-    const raw = (body ?? {});
-    const bounded = {};
-    for (const [key, value] of Object.entries(raw)) {
-        bounded[key] = typeof value === "string" ? value.slice(0, MAX_BODY_STRING_LENGTH) : value;
-    }
-    return bounded;
+    return (body ?? {});
 }
 /** True for a real browser's form-POST navigation (`Accept: text/html,...`); false for the
  *  fetch/XHR/API caller shape every pre-existing test in this file already sends (`*\/*`, or no

package/dist/forms/field-registry.d.ts

@@ -0,0 +1,193 @@
+/** The form field vocabulary and control semantics. Validation and rendering both read this registry. */
+import type { FieldDescriptor, FormAnswer, FormFileInput, FormFileStoragePort } from "./types.js";
+export type FieldResolution = {
+    kind: "absent";
+} | {
+    kind: "rejected";
+    reason: string;
+} | {
+    kind: "accepted";
+    value: FormAnswer;
+} | {
+    kind: "upload";
+    file: FormFileInput;
+};
+type FieldValidator = (required: {
+    field: FieldDescriptor;
+    value: unknown;
+}, optional?: Record<string, never>) => FieldResolution;
+/** Input length is capped before any format/pattern work, even on optional unconstrained text. */
+declare function textValue({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** Reuse the native email format owner after the shared text constraints. */
+declare function emailValue({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** Accept a bounded international telephone spelling without rewriting the answer. */
+declare function phoneValue({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** Parse absolute HTTP(S) URLs with the platform URL API; refuse active schemes and whitespace. */
+declare function urlValue({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** Native numeric text is parsed strictly, retaining finite JSON numbers as numbers in storage. */
+declare function numberValue({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** Recheck native calendar/clock syntax and configured bounds on the server. */
+declare function temporalValue({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** A scalar choice must be one of the stored option values; arrays never collapse silently. */
+declare function singleChoice({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** Normalize native one-value groups to arrays; duplicate and unlisted values are invalid. */
+declare function multipleChoice({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+/** Native boxes submit on or an authored value; required consent must be checked. */
+declare function booleanValue({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, _optional?: {}): FieldResolution;
+export declare const FIELD_TYPE_REGISTRY: {
+    readonly text: {
+        readonly control: "input";
+        readonly htmlType: "text";
+        readonly validate: typeof textValue;
+        readonly textual: true;
+    };
+    readonly textarea: {
+        readonly control: "textarea";
+        readonly htmlType: "textarea";
+        readonly validate: typeof textValue;
+        readonly textual: true;
+    };
+    readonly email: {
+        readonly control: "input";
+        readonly htmlType: "email";
+        readonly validate: typeof emailValue;
+        readonly textual: true;
+    };
+    readonly phone: {
+        readonly control: "input";
+        readonly htmlType: "tel";
+        readonly validate: typeof phoneValue;
+        readonly textual: true;
+    };
+    readonly url: {
+        readonly control: "input";
+        readonly htmlType: "url";
+        readonly validate: typeof urlValue;
+        readonly textual: true;
+    };
+    readonly number: {
+        readonly control: "input";
+        readonly htmlType: "number";
+        readonly validate: typeof numberValue;
+    };
+    readonly range: {
+        readonly control: "input";
+        readonly htmlType: "range";
+        readonly validate: typeof numberValue;
+    };
+    readonly date: {
+        readonly control: "input";
+        readonly htmlType: "date";
+        readonly validate: typeof temporalValue;
+    };
+    readonly time: {
+        readonly control: "input";
+        readonly htmlType: "time";
+        readonly validate: typeof temporalValue;
+    };
+    readonly datetime: {
+        readonly control: "input";
+        readonly htmlType: "datetime-local";
+        readonly validate: typeof temporalValue;
+    };
+    readonly select: {
+        readonly control: "select";
+        readonly htmlType: "select";
+        readonly validate: typeof singleChoice;
+        readonly choices: true;
+    };
+    readonly "multi-select": {
+        readonly control: "select";
+        readonly htmlType: "select";
+        readonly validate: typeof multipleChoice;
+        readonly choices: true;
+        readonly multiple: true;
+    };
+    readonly radio: {
+        readonly control: "group";
+        readonly htmlType: "radio";
+        readonly validate: typeof singleChoice;
+        readonly choices: true;
+    };
+    readonly checkbox: {
+        readonly control: "input";
+        readonly htmlType: "checkbox";
+        readonly validate: typeof booleanValue;
+    };
+    readonly "checkbox-group": {
+        readonly control: "group";
+        readonly htmlType: "checkbox";
+        readonly validate: typeof multipleChoice;
+        readonly choices: true;
+        readonly multiple: true;
+    };
+    readonly toggle: {
+        readonly control: "input";
+        readonly htmlType: "checkbox";
+        readonly validate: typeof booleanValue;
+    };
+    readonly file: {
+        readonly control: "input";
+        readonly htmlType: "file";
+        readonly validate: FieldValidator;
+    };
+    readonly hidden: {
+        readonly control: "input";
+        readonly htmlType: "hidden";
+        readonly validate: typeof textValue;
+        readonly textual: true;
+    };
+};
+/** Safe patterns support literals/classes and one repetition; no user-defined backtracking trees.
+ * @returns False for unsupported or invalid regex syntax, never throws. */
+export declare function isSafeFieldPattern({ pattern }: {
+    pattern: string;
+}, _optional?: {}): boolean;
+/** Browsers compile the `pattern` attribute with the `v` flag, which rejects some `u`-valid classes
+ * (an unescaped `-` as in `[a-z-]`, or `(`, `)`, `{`, `}`, `/`, `|` inside `[...]`). The browser
+ * then drops the attribute without a word and only the server enforces it (2026-10-11), so new
+ * authoring must pass both; submissions still validate with {@link isSafeFieldPattern} alone.
+ * @returns False when the pattern is unsafe or a browser would ignore it, never throws. */
+export declare function isBrowserSafeFieldPattern({ pattern }: {
+    pattern: string;
+}, _optional?: {}): boolean;
+/** Public forms accept only known inert media/document formats; wildcard accept never expands this list. */
+export declare const SAFE_FORM_FILE_TYPES: Readonly<Record<string, readonly string[]>>;
+export declare const MAX_FORM_FILE_BYTES: number;
+/** Checks byte size, MIME, filename and detected magic before any upload side effect.
+ * @complexity O(n) host sniffing, bounded by a 10 MiB per-file ceiling. */
+export declare function resolveFormField({ field, value }: {
+    field: FieldDescriptor;
+    value: unknown;
+}, { files }?: {
+    files?: Pick<FormFileStoragePort, "detectContentType">;
+}): FieldResolution;
+export {};
+//# sourceMappingURL=field-registry.d.ts.map

package/dist/forms/field-registry.js

@@ -0,0 +1,231 @@
+import { isValidFormEmail } from "./email-format.js";
+const accepted = (value) => ({ kind: "accepted", value });
+const rejected = (reason) => ({ kind: "rejected", reason });
+const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+const fullMatch = (pattern, value) => pattern.exec(value)?.[0] === value;
+/** Input length is capped before any format/pattern work, even on optional unconstrained text. */
+function textValue({ field, value }, _optional = {}) {
+    if (typeof value !== "string")
+        return rejected("must be a string");
+    if (field.required && value.trim() === "")
+        return rejected("required");
+    const maxLength = field.maxLength ?? 5000;
+    if (value.length > maxLength)
+        return rejected("too_long");
+    if (value !== "" && value.length < (field.minLength ?? Number(field.attributes?.minlength ?? 0)))
+        return rejected("too_short");
+    const pattern = field.pattern ?? field.attributes?.pattern;
+    if (value !== "" && pattern !== undefined) {
+        if (!isSafeFieldPattern({ pattern }) || !fullMatch(new RegExp(`^(?:${pattern})$`, "u"), value))
+            return rejected("pattern_mismatch");
+    }
+    return accepted(value);
+}
+/** Reuse the native email format owner after the shared text constraints. */
+function emailValue({ field, value }, _optional = {}) {
+    const result = textValue({ field, value });
+    if (result.kind !== "accepted" || value === "")
+        return result;
+    return isValidFormEmail({ value: value }) ? result : rejected("invalid_email");
+}
+/** Accept a bounded international telephone spelling without rewriting the answer. */
+function phoneValue({ field, value }, _optional = {}) {
+    const result = textValue({ field, value });
+    if (result.kind !== "accepted" || value === "")
+        return result;
+    return fullMatch(/^\+?[0-9() .-]{3,50}$/, value) && /\d/.test(value) ? result : rejected("invalid_phone");
+}
+/** Parse absolute HTTP(S) URLs with the platform URL API; refuse active schemes and whitespace. */
+function urlValue({ field, value }, _optional = {}) {
+    const result = textValue({ field, value });
+    if (result.kind !== "accepted" || value === "")
+        return result;
+    try {
+        const url = new URL(value);
+        return ["http:", "https:"].includes(url.protocol) && url.hostname !== "" && value.trim() === value ? result : rejected("invalid_url");
+    }
+    catch {
+        return rejected("invalid_url");
+    }
+}
+/** Native numeric text is parsed strictly, retaining finite JSON numbers as numbers in storage. */
+function numberValue({ field, value }, _optional = {}) {
+    if (value === "")
+        return field.required ? rejected("required") : { kind: "absent" };
+    if (typeof value !== "number" && (typeof value !== "string" || value.length > 100 || !fullMatch(NUMBER, value)))
+        return rejected("invalid_number");
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        return rejected("invalid_number");
+    const min = field.min ?? field.attributes?.min ?? (field.type === "range" ? 0 : undefined);
+    const max = field.max ?? field.attributes?.max ?? (field.type === "range" ? 100 : undefined);
+    if (min !== undefined && number < Number(min))
+        return rejected("below_min");
+    if (max !== undefined && number > Number(max))
+        return rejected("above_max");
+    const step = field.step ?? Number(field.attributes?.step ?? 1);
+    const units = (number - Number(min ?? 0)) / step;
+    if (!Number.isFinite(units) || Math.abs(units - Math.round(units)) > 1e-8)
+        return rejected("step_mismatch");
+    return accepted(number);
+}
+/** Calendar validation compares components so Date's rollover cannot accept February 30. */
+function validDate(value) {
+    if (!fullMatch(/^\d{4}-\d{2}-\d{2}$/, value))
+        return false;
+    const [year, month, day] = value.split("-").map(Number);
+    if (!year || !month || !day)
+        return false;
+    const date = new Date(`${value}T00:00:00Z`);
+    return date.getUTCFullYear() === year && date.getUTCMonth() + 1 === month && date.getUTCDate() === day;
+}
+const validTime = (value) => fullMatch(/(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,3})?)?/, value);
+/** Native controls carry local wall-clock values; UTC is used only as a comparison axis. */
+function temporalTimestamp(type, value) {
+    if (type === "date")
+        return Date.parse(`${value}T00:00:00Z`);
+    return Date.parse(type === "time" ? `1970-01-01T${value}Z` : `${value}Z`);
+}
+/** Recheck native calendar/clock syntax and configured bounds on the server. */
+function temporalValue({ field, value }, _optional = {}) {
+    if (typeof value !== "string" || value.length > 30)
+        return rejected("invalid_datetime");
+    if (value === "")
+        return field.required ? rejected("required") : { kind: "absent" };
+    const [date, time, extra] = value.split("T");
+    const valid = field.type === "date" ? validDate(value) : field.type === "time" ? validTime(value) : extra === undefined && validDate(date) && time !== undefined && validTime(time);
+    if (!valid)
+        return rejected(`invalid_${field.type}`);
+    const min = field.min ?? field.attributes?.min;
+    const max = field.max ?? field.attributes?.max;
+    // Compare normalized instants: 12:30 and 12:30:00, or .1 and .100 seconds, are equal.
+    const timestamp = temporalTimestamp(field.type, value);
+    if (min !== undefined && timestamp < temporalTimestamp(field.type, String(min)))
+        return rejected("below_min");
+    if (max !== undefined && timestamp > temporalTimestamp(field.type, String(max)))
+        return rejected("above_max");
+    return accepted(value);
+}
+/** A scalar choice must be one of the stored option values; arrays never collapse silently. */
+function singleChoice({ field, value }, _optional = {}) {
+    if (value === "")
+        return field.required ? rejected("required") : { kind: "absent" };
+    if (typeof value !== "string")
+        return rejected("must be a string");
+    return field.options?.some((option) => option.value === value) ? accepted(value) : rejected("invalid_option");
+}
+/** Normalize native one-value groups to arrays; duplicate and unlisted values are invalid. */
+function multipleChoice({ field, value }, _optional = {}) {
+    const values = typeof value === "string" ? [value] : value;
+    if (!Array.isArray(values) || values.length > 100 || !values.every((item) => typeof item === "string"))
+        return rejected("must be a string array");
+    if (field.required && values.length === 0)
+        return rejected("required");
+    const allowed = new Set(field.options?.map((option) => option.value));
+    if (new Set(values).size !== values.length || values.some((item) => !allowed.has(item)))
+        return rejected("invalid_option");
+    return accepted([...values]);
+}
+/** Native boxes submit on or an authored value; required consent must be checked. */
+function booleanValue({ field, value }, _optional = {}) {
+    if (field.checkboxValue !== undefined) {
+        if (typeof value !== "string")
+            return rejected("must be a boolean");
+        return value === field.checkboxValue ? accepted(value) : rejected("invalid_option");
+    }
+    if (typeof value === "boolean")
+        return field.required && !value ? rejected("required") : accepted(value);
+    return value === "on" ? accepted(true) : rejected("must be a boolean");
+}
+// File validation needs a host sniffer. The ordinary resolver refuses files without that port.
+const fileValue = (_required, _optional = {}) => rejected("file_storage_unavailable");
+export const FIELD_TYPE_REGISTRY = {
+    text: { control: "input", htmlType: "text", validate: textValue, textual: true },
+    textarea: { control: "textarea", htmlType: "textarea", validate: textValue, textual: true },
+    email: { control: "input", htmlType: "email", validate: emailValue, textual: true },
+    phone: { control: "input", htmlType: "tel", validate: phoneValue, textual: true },
+    url: { control: "input", htmlType: "url", validate: urlValue, textual: true },
+    number: { control: "input", htmlType: "number", validate: numberValue },
+    range: { control: "input", htmlType: "range", validate: numberValue },
+    date: { control: "input", htmlType: "date", validate: temporalValue },
+    time: { control: "input", htmlType: "time", validate: temporalValue },
+    datetime: { control: "input", htmlType: "datetime-local", validate: temporalValue },
+    select: { control: "select", htmlType: "select", validate: singleChoice, choices: true },
+    "multi-select": { control: "select", htmlType: "select", validate: multipleChoice, choices: true, multiple: true },
+    radio: { control: "group", htmlType: "radio", validate: singleChoice, choices: true },
+    checkbox: { control: "input", htmlType: "checkbox", validate: booleanValue },
+    "checkbox-group": { control: "group", htmlType: "checkbox", validate: multipleChoice, choices: true, multiple: true },
+    toggle: { control: "input", htmlType: "checkbox", validate: booleanValue },
+    file: { control: "input", htmlType: "file", validate: fileValue },
+    hidden: { control: "input", htmlType: "hidden", validate: textValue, textual: true },
+};
+/** Safe patterns support literals/classes and one repetition; no user-defined backtracking trees.
+ * @returns False for unsupported or invalid regex syntax, never throws. */
+export function isSafeFieldPattern({ pattern }, _optional = {}) {
+    if (pattern.length > 300 || /[()|]|\\[1-9]|\\[pPkK]/.test(pattern))
+        return false;
+    // Multiple repetitions can still backtrack exponentially without parentheses; refuse them too.
+    const outsideClasses = pattern.replace(/\\./g, "x").replace(/\[[^\]]*\]/g, "x");
+    if ((outsideClasses.match(/[+*?]|\{/g) ?? []).length > 1 || /\.\*/.test(outsideClasses))
+        return false;
+    try {
+        new RegExp(`^(?:${pattern})$`, "u");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Browsers compile the `pattern` attribute with the `v` flag, which rejects some `u`-valid classes
+ * (an unescaped `-` as in `[a-z-]`, or `(`, `)`, `{`, `}`, `/`, `|` inside `[...]`). The browser
+ * then drops the attribute without a word and only the server enforces it (2026-10-11), so new
+ * authoring must pass both; submissions still validate with {@link isSafeFieldPattern} alone.
+ * @returns False when the pattern is unsafe or a browser would ignore it, never throws. */
+export function isBrowserSafeFieldPattern({ pattern }, _optional = {}) {
+    if (!isSafeFieldPattern({ pattern }))
+        return false;
+    try {
+        new RegExp(`^(?:${pattern})$`, "v");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Public forms accept only known inert media/document formats; wildcard accept never expands this list. */
+export const SAFE_FORM_FILE_TYPES = {
+    "image/png": ["png"], "image/jpeg": ["jpg", "jpeg"], "image/gif": ["gif"], "image/webp": ["webp"], "image/avif": ["avif"],
+    "video/mp4": ["mp4"], "video/webm": ["webm"], "application/pdf": ["pdf"],
+};
+export const MAX_FORM_FILE_BYTES = 10 * 1024 * 1024;
+const DANGEROUS_EXTENSION = /\.(?:exe|dll|com|bat|cmd|msi|sh|bash|ps1|js|mjs|cjs|ts|tsx|jsx|py|rb|pl|php\d*|phtml|html?|svg|xml|jar|zip|scr|vbs)(?:\.|$)/i;
+/** Checks byte size, MIME, filename and detected magic before any upload side effect.
+ * @complexity O(n) host sniffing, bounded by a 10 MiB per-file ceiling. */
+export function resolveFormField({ field, value }, { files } = {}) {
+    if (value === undefined || value === null)
+        return field.required ? rejected("required") : { kind: "absent" };
+    const kind = Object.hasOwn(FIELD_TYPE_REGISTRY, field.type) ? FIELD_TYPE_REGISTRY[field.type] : undefined;
+    if (!kind)
+        return rejected("invalid_type");
+    if (field.type !== "file")
+        return kind.validate({ field, value });
+    if (!files)
+        return rejected("file_storage_unavailable");
+    const file = value;
+    if (typeof file !== "object" || !(file.bytes instanceof Uint8Array) || typeof file.filename !== "string" || typeof file.contentType !== "string")
+        return rejected("invalid_file");
+    if (file.bytes.byteLength === 0 || file.bytes.byteLength > Math.min(field.maxFileSize ?? MAX_FORM_FILE_BYTES, MAX_FORM_FILE_BYTES))
+        return rejected("file_size");
+    if (file.filename.length > 200 || /[\\/\x00-\x1f\x7f]/.test(file.filename) || DANGEROUS_EXTENSION.test(file.filename))
+        return rejected("file_type");
+    const contentType = files.detectContentType({ bytes: file.bytes });
+    if (file.contentType !== "" && file.contentType !== contentType)
+        return rejected("file_type");
+    const extensions = Object.hasOwn(SAFE_FORM_FILE_TYPES, contentType) ? SAFE_FORM_FILE_TYPES[contentType] : undefined;
+    if (!extensions || !extensions.includes(file.filename.split(".").at(-1).toLowerCase()))
+        return rejected("file_type");
+    if (field.accept && !field.accept.some((accept) => accept === contentType || accept === "*/*" || accept === `${contentType.split("/")[0]}/*`))
+        return rejected("file_type");
+    return { kind: "upload", file: { filename: file.filename, contentType, bytes: file.bytes } };
+}
+//# sourceMappingURL=field-registry.js.map

package/dist/forms/forms.d.ts

@@ -1,5 +1,5 @@
 /** Pure field/submission validation and honeypot decisions. Error order and stored value normalization are stable. */
-import type { FieldDescriptor, FormDefinitionRecord } from "./types.js";
+import type { FieldDescriptor, FormDefinitionRecord, FormAnswer, FormFileInput, FormFileStoragePort } from "./types.js";
 export declare const MAX_FIELDS = 20;
 export declare const MAX_LABEL_LENGTH = 200;
 export declare const MIN_MAX_LENGTH = 1;
@@ -35,14 +35,15 @@ export type FieldValidationResult = {
  */
 export declare function validateFieldDescriptors({ fields }: {
     fields: FieldDescriptor[];
-}): FieldValidationResult;
+}, _optional?: {}): FieldValidationResult;
 export interface ValidateSubmissionPayloadInput {
     definition: FormDefinitionRecord;
     body: Record<string, unknown>;
 }
 export type SubmissionValidationResult = {
     valid: true;
-    data: Record<string, string | boolean>;
+    data: Record<string, FormAnswer>;
+    files?: Record<string, FormFileInput>;
 } | {
     valid: false;
     fieldErrors: FieldError[];
@@ -52,8 +53,10 @@ export type SubmissionValidationResult = {
  * body keys first, then declared-field errors in definition order, independent of body key order.
  * This keeps the declared-field portion of the error list stable across equivalent submissions.
  */
-export declare function validateSubmissionPayload(input: ValidateSubmissionPayloadInput): SubmissionValidationResult;
+export declare function validateSubmissionPayload(input: ValidateSubmissionPayloadInput, optional?: {
+    files?: Pick<FormFileStoragePort, "detectContentType">;
+}): SubmissionValidationResult;
 export declare function isHoneypotTripped(input: {
     hp: unknown;
-}): boolean;
+}, _optional?: {}): boolean;
 //# sourceMappingURL=forms.d.ts.map