@stacksjs/forms 0.74.1 → 0.74.3

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export type {
   SubmissionErrors,
   ValidateSubmissionResult,
 } from './types';
+export type { UploadLimits, UploadRejection } from './uploads';
 export { evaluateConditions, visibleFields } from './conditions';
 export { createForm, loadFormByHandle, toCreateFields } from './create';
 export { loadFormByUuid, publicDefinition } from './definition';
@@ -23,4 +24,12 @@ export {
   fetchSubmissions,
   submitForm,
 } from './submissions';
+export {
+  checkUpload,
+  extensionOf,
+  fileFieldNamed,
+  formUploadPrefix,
+  isOwnedUploadPath,
+  resolveUploadLimits,
+} from './uploads';
 export { computeAmountCents, validateSubmission } from './validate';

package/dist/index.js

@@ -1 +1 @@
-export{evaluateConditions,visibleFields}from"./conditions";export{createForm,loadFormByHandle,toCreateFields}from"./create";export{loadFormByUuid,publicDefinition}from"./definition";export{dispatchSubmissionNotifications}from"./notifications";export{completeSubmissionPayment,exportSubmissionsCsv,fetchSubmissions,submitForm}from"./submissions";export{computeAmountCents,validateSubmission}from"./validate";
+export{evaluateConditions,visibleFields}from"./conditions";export{createForm,loadFormByHandle,toCreateFields}from"./create";export{loadFormByUuid,publicDefinition}from"./definition";export{dispatchSubmissionNotifications}from"./notifications";export{completeSubmissionPayment,exportSubmissionsCsv,fetchSubmissions,submitForm}from"./submissions";export{checkUpload,extensionOf,fileFieldNamed,formUploadPrefix,isOwnedUploadPath,resolveUploadLimits}from"./uploads";export{computeAmountCents,validateSubmission}from"./validate";

package/dist/uploads.d.ts

@@ -0,0 +1,70 @@
+import type { FormDefinition, FormFieldDefinition } from './types';
+/** Lowercase extension of a filename, without the dot. `''` when it has none. */
+export declare function extensionOf(filename: string): string;
+/**
+ * The ceilings for one field: the field's own options win over the app's
+ * defaults, which win over the framework's.
+ *
+ * A field saying `accept: ['pdf']` on a form whose config allows images is
+ * asking for something narrower, and narrower is the answer that cannot
+ * surprise anyone. The reverse — a field widening past the app's config — is
+ * NOT honoured: the config is the app's ceiling and a form builder should not
+ * be able to raise it.
+ */
+export declare function resolveUploadLimits(field: FormFieldDefinition): UploadLimits;
+/**
+ * The storage prefix that owns a form's uploads.
+ *
+ * `validate.ts` has always said "the prefix pins it to this form's upload
+ * area, so a submission cannot reference someone else's file" — while checking
+ * only the value's length. This is the prefix that comment was describing, and
+ * `checkField` now actually tests it.
+ */
+export declare function formUploadPrefix(form: Pick<FormDefinition, 'uuid'>): string;
+/** Is this stored path inside the form's own upload area? */
+export declare function isOwnedUploadPath(form: Pick<FormDefinition, 'uuid'>, path: unknown): boolean;
+/**
+ * Check one incoming file against a field's ceilings.
+ *
+ * Returns null when it is acceptable. The size check comes first: an oversized
+ * file of a disallowed type should report the size, because that is the one
+ * the person cannot fix by renaming.
+ */
+export declare function checkUpload(field: FormFieldDefinition, file: { name?: string, size?: number }, limits?: UploadLimits): UploadRejection | null;
+/** The `file` field with this name on a form, or null. */
+export declare function fileFieldNamed(form: FormDefinition, name: unknown): FormFieldDefinition | null;
+/**
+ * File uploads for a form's `file` fields.
+ *
+ * `config/forms.ts` has declared `uploads: { disk, maxSizeMb, allowedTypes }`
+ * since the bundle shipped, fully typed and documented — and nothing read any
+ * of it. An app could set `maxSizeMb: 2` and `allowedTypes: ['pdf']` and
+ * neither was ever applied, because the only check on a `file` field was that
+ * its value is a string under 1024 characters. stacksjs/stacks#2406.
+ *
+ * Enforced server-side rather than through a presigned policy, deliberately.
+ * A presign lets the browser upload straight to storage, which means the size
+ * ceiling has to be expressed in the policy and the type ceiling cannot really
+ * be expressed at all — S3 checks the `Content-Type` the CLIENT declared. Here
+ * the server has the bytes, so both limits are checked against what actually
+ * arrived, and the same code path works on a local disk. A public form is not
+ * a bulk-upload surface; 10MB through the app is not the bottleneck.
+ */
+/** Resolved ceilings for one file field. */
+export declare interface UploadLimits {
+  disk?: string
+  maxBytes: number
+  allowedTypes: string[]
+}
+/**
+ * Why an upload was refused, in the shape the endpoint answers with.
+ *
+ * The status is the literal union rather than `number` so the route can hand
+ * it straight to `response.json`, whose `ResponseStatus` is a union of literal
+ * codes. A widened `number` there forces a cast at the call site, and a cast
+ * is how a status nobody intended eventually gets returned.
+ */
+export declare interface UploadRejection {
+  status: 413 | 422
+  message: string
+}

package/dist/uploads.js

@@ -0,0 +1 @@
+import{config}from"@stacksjs/config";const DEFAULT_MAX_SIZE_MB=10,DEFAULT_ALLOWED_TYPES=["pdf","png","jpg","jpeg","webp","doc","docx"];function uploadConfig(){return config.forms?.uploads??{}}export function extensionOf(filename){const base=filename.split("/").pop()??"",dot=base.lastIndexOf(".");return dot>0?base.slice(dot+1).toLowerCase():""}export function resolveUploadLimits(field){const appConfig=uploadConfig(),appMaxMb=appConfig.maxSizeMb??DEFAULT_MAX_SIZE_MB,appTypes=(appConfig.allowedTypes??DEFAULT_ALLOWED_TYPES).map((type)=>type.toLowerCase().replace(/^\./,"")),fieldMaxMb=field.options?.maxSizeMb,maxMb=typeof fieldMaxMb==="number"&&fieldMaxMb>0?Math.min(fieldMaxMb,appMaxMb):appMaxMb,fieldTypes=field.options?.accept?.map((type)=>type.toLowerCase().replace(/^\./,"")),allowedTypes=fieldTypes?.length?fieldTypes.filter((type)=>appTypes.includes(type)):appTypes;return{disk:appConfig.disk,maxBytes:Math.round(maxMb*1024*1024),allowedTypes}}export function formUploadPrefix(form){return`forms/${form.uuid}`}export function isOwnedUploadPath(form,path){if(typeof path!=="string"||path.length===0||path.length>1024)return!1;if(path.includes("..")||path.startsWith("/")||path.includes("://")||path.includes("\\"))return!1;return path.startsWith(`${formUploadPrefix(form)}/`)}export function checkUpload(field,file,limits=resolveUploadLimits(field)){const size=Number(file.size??0);if(!Number.isFinite(size)||size<=0)return{status:422,message:`${field.label} upload is empty.`};if(size>limits.maxBytes){const mb=(limits.maxBytes/1048576).toFixed(limits.maxBytes%1048576===0?0:1);return{status:413,message:`${field.label} must be ${mb} MB or smaller.`}}const extension=extensionOf(String(file.name??""));if(limits.allowedTypes.length>0&&!limits.allowedTypes.includes(extension))return{status:422,message:`${field.label} must be one of: ${limits.allowedTypes.join(", ")}.`};return null}export function fileFieldNamed(form,name){if(typeof name!=="string"||!name)return null;const field=form.fields.find((candidate)=>candidate.name===name);return field&&field.type==="file"?field:null}

package/dist/validate.js

@@ -1 +1 @@
-import{visibleFields}from"./conditions";const EMAIL_RE=/^[^\s@]+@[^\s@]+\.[^\s@]+$/,PHONE_RE=/^[\d\s()+.\-ext]{7,32}$/i;function isBlank(value){return value===void 0||value===null||typeof value==="string"&&value.trim()===""}function checkField(field,value){const options=field.options??{};if(isBlank(value))return field.required?`${field.label} is required`:null;switch(field.type){case"text":case"textarea":{if(typeof value!=="string")return`${field.label} must be text`;const max=options.max??(field.type==="text"?500:1e4);if(value.length>max)return`${field.label} must be at most ${max} characters`;if(options.min&&value.length<options.min)return`${field.label} must be at least ${options.min} characters`;return null}case"email":return typeof value==="string"&&EMAIL_RE.test(value)&&value.length<=255?null:`${field.label} must be a valid email address`;case"phone":return typeof value==="string"&&PHONE_RE.test(value)?null:`${field.label} must be a valid phone number`;case"select":case"radio":{const choices=(options.choices??[]).map((choice)=>choice.value);return typeof value==="string"&&choices.includes(value)?null:`${field.label} must be one of the listed choices`}case"checkbox":return typeof value==="boolean"||value==="true"||value==="false"?null:`${field.label} must be a yes or no`;case"date":{if(typeof value!=="string"||Number.isNaN(Date.parse(value)))return`${field.label} must be a valid date`;return null}case"file":return typeof value==="string"&&value.length<=1024?null:`${field.label} upload is invalid`;case"currency":{const cents=Number(value);if(!Number.isInteger(cents)||cents<0)return`${field.label} must be a whole amount`;if(options.min!==void 0&&cents<options.min)return`${field.label} must be at least ${options.min}`;if(options.max!==void 0&&cents>options.max)return`${field.label} must be at most ${options.max}`;return null}case"section_break":return null;default:return`${field.label} has an unknown type`}}function coerce(field,value){if(field.type==="checkbox")return value===!0||value==="true";if(field.type==="currency")return Number(value);return value}function pickEmail(form,fields,values){const named=form.settings.emailField,field=named?fields.find((candidate)=>candidate.name===named):fields.find((candidate)=>candidate.type==="email"),value=field?values[field.name]:void 0;return typeof value==="string"&&value?value.toLowerCase():null}function pickName(form,fields,values){const named=form.settings.nameField,field=named?fields.find((candidate)=>candidate.name===named):fields.find((candidate)=>candidate.type==="text"&&/name/i.test(candidate.name)),value=field?values[field.name]:void 0;return typeof value==="string"&&value?value:null}export function computeAmountCents(form,fields,values){const payment=form.settings.payment;if(!payment)return null;switch(payment.mode){case"fixed":return payment.amountCents??0;case"field_sum":return fields.filter((field)=>field.type==="currency").reduce((sum,field)=>sum+(Number(values[field.name])||0),0);case"user_amount":{const field=payment.amountField?fields.find((candidate)=>candidate.name===payment.amountField):fields.find((candidate)=>candidate.type==="currency"),cents=field?Number(values[field.name])||0:0,floor=payment.minAmountCents??0;return Math.max(cents,floor)}default:return null}}export function validateSubmission(form,payload){const fields=visibleFields(form.fields,payload),errors={},values={};for(const field of fields){if(field.type==="section_break")continue;const raw=payload[field.name],problem=checkField(field,raw);if(problem){errors[field.name]=problem;continue}if(!isBlank(raw))values[field.name]=coerce(field,raw)}if(Object.keys(errors).length>0)return{ok:!1,errors};return{ok:!0,values,email:pickEmail(form,fields,values),name:pickName(form,fields,values),amountCents:computeAmountCents(form,fields,values)}}
+import{visibleFields}from"./conditions";import{isOwnedUploadPath}from"./uploads";const EMAIL_RE=/^[^\s@]+@[^\s@]+\.[^\s@]+$/,PHONE_RE=/^[\d\s()+.\-ext]{7,32}$/i;function isBlank(value){return value===void 0||value===null||typeof value==="string"&&value.trim()===""}function checkField(field,value,form){const options=field.options??{};if(isBlank(value))return field.required?`${field.label} is required`:null;switch(field.type){case"text":case"textarea":{if(typeof value!=="string")return`${field.label} must be text`;const max=options.max??(field.type==="text"?500:1e4);if(value.length>max)return`${field.label} must be at most ${max} characters`;if(options.min&&value.length<options.min)return`${field.label} must be at least ${options.min} characters`;return null}case"email":return typeof value==="string"&&EMAIL_RE.test(value)&&value.length<=255?null:`${field.label} must be a valid email address`;case"phone":return typeof value==="string"&&PHONE_RE.test(value)?null:`${field.label} must be a valid phone number`;case"select":case"radio":{const choices=(options.choices??[]).map((choice)=>choice.value);return typeof value==="string"&&choices.includes(value)?null:`${field.label} must be one of the listed choices`}case"checkbox":return typeof value==="boolean"||value==="true"||value==="false"?null:`${field.label} must be a yes or no`;case"date":{if(typeof value!=="string"||Number.isNaN(Date.parse(value)))return`${field.label} must be a valid date`;return null}case"file":return isOwnedUploadPath(form,value)?null:`${field.label} upload is invalid`;case"currency":{const cents=Number(value);if(!Number.isInteger(cents)||cents<0)return`${field.label} must be a whole amount`;if(options.min!==void 0&&cents<options.min)return`${field.label} must be at least ${options.min}`;if(options.max!==void 0&&cents>options.max)return`${field.label} must be at most ${options.max}`;return null}case"section_break":return null;default:return`${field.label} has an unknown type`}}function coerce(field,value){if(field.type==="checkbox")return value===!0||value==="true";if(field.type==="currency")return Number(value);return value}function pickEmail(form,fields,values){const named=form.settings.emailField,field=named?fields.find((candidate)=>candidate.name===named):fields.find((candidate)=>candidate.type==="email"),value=field?values[field.name]:void 0;return typeof value==="string"&&value?value.toLowerCase():null}function pickName(form,fields,values){const named=form.settings.nameField,field=named?fields.find((candidate)=>candidate.name===named):fields.find((candidate)=>candidate.type==="text"&&/name/i.test(candidate.name)),value=field?values[field.name]:void 0;return typeof value==="string"&&value?value:null}export function computeAmountCents(form,fields,values){const payment=form.settings.payment;if(!payment)return null;switch(payment.mode){case"fixed":return payment.amountCents??0;case"field_sum":return fields.filter((field)=>field.type==="currency").reduce((sum,field)=>sum+(Number(values[field.name])||0),0);case"user_amount":{const field=payment.amountField?fields.find((candidate)=>candidate.name===payment.amountField):fields.find((candidate)=>candidate.type==="currency"),cents=field?Number(values[field.name])||0:0,floor=payment.minAmountCents??0;return Math.max(cents,floor)}default:return null}}export function validateSubmission(form,payload){const fields=visibleFields(form.fields,payload),errors={},values={};for(const field of fields){if(field.type==="section_break")continue;const raw=payload[field.name],problem=checkField(field,raw,form);if(problem){errors[field.name]=problem;continue}if(!isBlank(raw))values[field.name]=coerce(field,raw)}if(Object.keys(errors).length>0)return{ok:!1,errors};return{ok:!0,values,email:pickEmail(form,fields,values),name:pickName(form,fields,values),amountCents:computeAmountCents(form,fields,values)}}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/forms",
   "type": "module",
-  "version": "0.74.1",
+  "version": "0.74.3",
   "description": "The Stacks form-builder functionality.",
   "author": "Chris Breuer",
   "contributors": [
@@ -56,14 +56,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.74.1",
-    "@stacksjs/database": "0.74.1",
-    "@stacksjs/logging": "0.74.1",
-    "@stacksjs/notifications": "0.74.1"
+    "@stacksjs/config": "0.74.3",
+    "@stacksjs/database": "0.74.3",
+    "@stacksjs/logging": "0.74.3",
+    "@stacksjs/notifications": "0.74.3"
   },
   "devDependencies": {
-    "@stacksjs/storage": "0.74.1",
-    "@stacksjs/validation": "0.74.1",
+    "@stacksjs/storage": "0.74.3",
+    "@stacksjs/validation": "0.74.3",
     "better-dx": "^0.2.24"
   },
   "sideEffects": false