# Validation, security, retention, and attachments

Last reviewed: 2026-10-16. Contract: Forms `/v1` submission parsing/verification,
rules schema, dashboard settings, and S3 upload constants. Verify self-hosted
release/configuration before relying on these limits.

## Field rules and enabled state

Copy the real endpoint/key from the dashboard. Field `name` attributes/JSON keys
must match configured rule field names exactly; a matching label is insufficient.
Configured rules run server-side on non-file values before storage/delivery.
Mirror them in the browser for usability, not as the only validation boundary.
Test required/format/length rules against the actual saved rule configuration;
do not invent unsupported rule options. Non-string JSON values are normalized
to strings, nulls are omitted, and repeated multipart names can form arrays.

When rules are present, the generated object schema is strict: unexpected
non-file field names also fail validation. Include every intended text field in
the saved rule inventory, not just the required ones. Supported rule kinds are
`required`, `email`, `url`, `number`, `phoneNumber`, `minLength`, `maxLength`,
`contains`, and `notContains`. For a `number` field, the length-named bounds are
numeric min/max checks; do not describe them as digit-count validation.

A disabled form rejects submissions (REST 409). An unknown form returns 404;
security/subscription checks may reject before field validation. Inspect the
HTTP status and response envelope, not only an error message string.

## Approval-gated contact rules recipe

This is a proposed template for a contact form whose ordinary fields are exactly
`name`, `email`, and `message`, not permission to change an existing form:

```json title="contact-rules.json"
{
  "version": 1,
  "fields": [
    { "name": "name", "rules": [{ "kind": "required" }] },
    {
      "name": "email",
      "rules": [{ "kind": "required" }, { "kind": "email" }]
    },
    { "name": "message", "rules": [{ "kind": "required" }] }
  ]
}
```

1. Read the current form, saved rules, and exact configured honeypot name using
   available read tools or the dashboard. Confirm the actual submitted fields.
2. Merge the proposed requirements with existing fields and constraints. Preserve
   unrelated rules and optional ordinary fields; do not silently weaken an email
   length rule, remove a consent field, or submit duplicate field definitions.
   Show conflicts and the full proposed replacement/diff for user approval.
3. Exclude the configured honeypot from ordinary rules: the submission parser
   removes it before rule validation. Its name must not collide with a real field.
   Unexpected ordinary text fields fail strict matching; intended optional fields
   still need a rule inventory entry, even if their `rules` array is empty.
4. Only after approval, confirm the target form and current rules again. The
   `set_form_rules` operation, when exposed, replaces the entire configuration;
   it is not a patch. Reconcile concurrent changes before writing. If no permitted
   tool exists, give dashboard instructions and identify sign-in/role requirements.
5. Read back the saved configuration and test required/format/unknown-field cases
   with mocks. A real submission needs separate approval, including delivery effects.

HTML `required` and `type="email"` improve usability; they do not configure
server-side rules. File controls follow upload settings, not text-field rules.

## Security settings are layers, not authentication

- Use the exact configured honeypot name. Leave it empty, avoid real input
  names, and do not rely on an undocumented `_trap` convention. The parser
  removes that field and rejects a nonempty string with 403.
- Website restrictions inspect available referrer metadata. They are not
  cryptographic proof of origin and can depend on missing/referrer-policy headers.
- IP blocking depends on the deployment's observed/forwarded IP metadata and
  configured valid addresses. Proxies and shared IPs affect results.
- CORS and client-side validation do not prevent all abuse. Public submission
  URLs are visible to browser users; they are not private account tokens.
- Keep private API/MCP tokens and downstream credentials on the server. Never
  paste secrets into public Markdown, an example payload, or client env variables.

## Retention and privacy

Enable retention if submissions must be stored, files persisted, or AI spam
analysis run. With retention off, do not promise dashboard history or stored
attachments/AI analysis. Webhook/email jobs can still be enqueued; review all
destinations even if storage is disabled. Delivery is asynchronous and not
guaranteed by a successful submission response.

The optional submission-data query string can put data in the success URL.
Keep it disabled for sensitive forms: URLs can reach browser history, logs,
analytics, screenshots, and referrers. Minimize collected fields and establish
consent/retention appropriate to the user's application. Use synthetic data for
tests; never log whole submissions by default.

## Files: configure before implementing

Current constants: **1 MiB (1,048,576 bytes) per file**, **five files per
submission**. These are total submission limits, not five per input. Exceeding
them produces 413; attaching files when uploads are disabled produces 400.
Enable both retention and file uploads in General settings. The dashboard
disables upload configuration without retention; persistence occurs inside
the retention branch. Do not rely on acceptance as proof files were stored.

Use named `<input type="file">` fields. Native HTML needs
`enctype="multipart/form-data"`; fetch uses `new FormData(form)` with
`Accept: application/json` and `?mode=rest`. **Do not manually set multipart
Content-Type or a boundary**, and do not turn files into JSON/base64 strings.
Browser-side size/count checks improve feedback but server checks remain
authoritative. An HTML `accept` attribute is a picker hint, not a security scan.

File-valued fields are excluded from webhook/email data (the whole field is
excluded if an array contains a file). Do not promise downstream attachments,
virus scanning, public download links, or arbitrary upload size overrides.
Treat filenames, MIME types, and file contents as untrusted at every consumer.

## Verification checklist

Mock: exact-limit and over-limit files, five versus six files across inputs,
empty file controls, duplicate names, uploads disabled, retention off, rule
failure, honeypot rejection, wrong/disabled form, and failed file persistence.
Test network/JSON failures and preserve inputs on failure. Do not automatically
retry ambiguous submissions; duplicate acceptance/delivery can occur. Live
storage/notification tests require user permission on a non-production form.

Human docs: [Rules](https://docs.basestack.co/content/forms/features/rules),
[Security settings](https://docs.basestack.co/content/forms/user-guide/settings-security),
[File uploads](https://docs.basestack.co/content/forms/features/file-uploads).
