A server-blind, browser-native encrypted form poster.

Form submissions are encrypted in the browser using X25519 sealed boxes before reaching your endpoint. The backend stores ciphertext prefixed with formseal.. Decryption is operator-controlled.

formseal-embed is not a hosted service, dashboard, or SaaS. It is a drop-in client-side utility.

Installation

Via pipx (recommended)

pipx install formseal-embed

Via pip

pip install formseal-embed

Quick start

fse init
fse set endpoint
fse set key
fse set origin
fse status

See Getting started for key generation.

How it works

Browser (formseal-embed)
│
▼ (encrypted submissions)
Your server / endpoint
│
▼ (fsf fetch — optional)
Your local machine

On submit, formseal:

1. Collects field values by name attribute
2. Validates against fields.jsonl
3. Seals the payload with crypto_box_seal
4. POSTs ciphertext (prefixed formseal.) to your endpoint

Your endpoint stores the ciphertext. Only the holder of the private key can decrypt.

Commands

Command	Description
fse	Show about / info
fse init	Scaffold formseal-embed into your project
fse set	Configure endpoint, public key, origin
fse field	Manage form fields
fse keygen	Generate an X25519 key pair
fse status	Show current configuration
fse reset	Remove and re-scaffold

Run fse --help for all options.

Security guarantee

If the endpoint is fully compromised, seized, or maliciously operated, previously submitted form data remains confidential.

Encryption happens in the browser. The backend stores ciphertext only. Decryption keys never exist in the backend environment. A backend compromise yields no recoverable plaintext.

Wire up your HTML

After fse init, files live in ./formseal-embed/. Reference them via your server's static path (e.g. /formseal-embed/globals.js).

<formid="contact-form"><!-- honeypot — hide off-screen with CSS --><inputtype="text" name="_hp" tabindex="-1" autocomplete="off"
style="position:absolute;left:-9999px;opacity:0;height:0;"><inputtype="text" name="name"><spandata-fse-error="name"></span><inputtype="email" name="email"><spandata-fse-error="email"></span><textareaname="message"></textarea><spandata-fse-error="message"></span><buttontype="submit" id="contact-submit">Send message</button></form><divid="contact-status"></div><script>window.fseCallbacks={onSuccess: ()=>document.getElementById('contact-status').textContent='Sent securely.',onError: (err)=>console.error('formseal error:',err),};</script><scriptsrc="/formseal-embed/globals.js"></script>

Payload format

{
"version": "fse.v1.0",
"origin": "contact-form",
"id": "<uuid>",
"submitted_at": "<iso8601>",
"data": {
"name": "...",
"email": "...",
"message": "..."
}
}

The entire object is sealed with crypto_box_seal. Your endpoint receives ciphertext prefixed with formseal. as the request body.

No IP, no timezone, no fingerprints — just the data you explicitly collect.

Field configuration

Fields are defined in fields.jsonl (one JSON object per line):

{"name": {"required": true, "maxLength": 100}}
{"email": {"required": true, "type": "email"}}
{"message": {"required": true, "maxLength": 1000}}

Manage fields with the CLI:

fse field add phone type:tel required:false
fse field remove company

CSS hooks

Selector	When
[data-fse-error="field"]	Populated with a validation error
[aria-invalid="true"]	Set on invalid inputs
[data-fse-status="success"]	Set on status element on success
[data-fse-status="error"]	Set on status element on error

What formseal-embed does not do

• No admin dashboard or inbox UI
• No hosted service
• No bundled decryption tools (yet)
• No npm dependencies at runtime

These are intentional.

Documentation

Full documentation is in the docs directory.

For developers

• CONTRIBUTING.md — Full contributing guide

License

MIT