durable-static-site-forms
Use when a static site must actually store form submissions.
- License 许可
- MIT
- 最近更新
- 2026-08-25
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- durable-static-site-forms
- version
- 1.0.0
- metadata
- { "tags": [ "forms", "static-sites", "sqlite", "privacy", "deployment" ] }
- description
- Use when a static site must actually store form submissions.
02 资源文件 1
- 参考文档references/caddy-sqlite-sidecar.md3.4 KB
03 SKILL.md 正文
Durable static-site forms
Turn a form on a static or serverless-hosted site into real, durable data capture. A prepared email is not a submitted lead. Completion means the server acknowledged the request and the record can be read back from the system of record.
1. Choose storage that matches the runtime
First classify the host:
- Ephemeral serverless filesystem: do not put the system of record in local SQLite or
/tmp. Use a managed database or a separate long-lived service. - Long-lived server or container host: SQLite is valid when one small service owns the database file on a persistent volume.
- No authenticated backend available: use a transparent mail-client flow only if the stakeholder accepts manual send. Say "prepared", not "sent".
Reject SQLite-over-object-storage, commit-the-database-to-Git, and other concurrency workarounds. They are fragile substitutes for a database owner.
Completion criterion: the selected store survives process restarts and redeploys, and one component owns writes.
2. Freeze the form contract
Name the browser origin, API URL, payload, consent, retention, and success semantics before editing.
A minimal lead has:
- optional display name;
- required contact;
- explicit consent;
- empty honeypot;
- server-assigned creation time, source, status, and identifier.
Validate body size, content type, field lengths, contact shape, consent, and origin at the HTTP boundary. Use parameterized SQL. Never interpolate form values into SQL, HTML, logs, or URLs.
Support both:
- JSON for enhanced browser submission;
application/x-www-form-urlencodedfor native no-JavaScript submission.
A native success may return 303 to the originating page. JavaScript success requires a successful HTTP response, then resets the form and reports the stored state.
3. Minimize retained data
Store only what the follow-up workflow needs. Do not retain raw IP addresses or browser user agents by default.
For abuse controls:
- derive a keyed hash from the client address;
- keep a separate short-lived attempt table;
- deduplicate a normalized contact with a keyed hash;
- rate-limit attempts, not only inserted rows;
- return success for a filled honeypot without storing it.
A retention promise needs an independent mechanism. Cleanup only during new submissions can miss the deadline when traffic stops. Run cleanup on startup and from a timer or background sweep; keeping transaction-time cleanup is useful as a second guard.
Completion criterion: the privacy copy matches the actual schema and cleanup schedule.
4. Establish a trusted proxy boundary
CORS is not authentication and public forwarding headers are attacker-controlled.
If a reverse proxy is the only caller that can reach the service:
- keep the application port off the public host network;
- connect proxy and service through a private network;
- remove public
CF-Connecting-IPandX-Forwarded-Forheaders; - overwrite one private application-specific header with the proxy's observed remote address;
- make the application reject requests that lack that private header;
- hash the value before storage.
Do not read a fallback IP from arbitrary public headers. Prove spoof resistance by rotating submitted forwarding headers from one real client and showing the rate limiter still sees one identity.
5. Deploy without coupling lifecycles
Keep the form API in its own image, Compose project, data directory, and health check. Reuse a shared reverse proxy only for ingress.
Use:
- an immutable image tag tied to the committed revision;
- a secret salt in a protected runtime env file;
- read-only container root filesystem;
- dropped Linux capabilities and
no-new-privileges; - a persistent data mount;
- a health endpoint that reads SQLite;
- a documented local-only export command.
When changing a file-mounted Caddyfile, preserve the mounted inode or recreate the proxy container. Replacing the host path can leave the running container pinned to the old inode. A successful reload of unchanged config is not proof the new host file is active.
Detailed Caddy and SQLite pattern: references/caddy-sqlite-sidecar.md.
6. Prove the complete chain
Run checks in this order:
- pure validation and database tests;
- native form and JSON API tests;
- rate-limit, dedupe, honeypot, origin, and retention tests;
- container build and health check;
- reverse-proxy candidate validation;
- local responsive form QA;
- production TLS and health read-back;
- one real production submission;
- exact SQLite read-back of that row;
- deletion of the synthetic row and
PRAGMA quick_check.
Also fetch the deployed JavaScript and confirm it uses the API, reports success only after HTTP acknowledgement, and contains no obsolete mailto: path.
Completion criterion: a production submission becomes one durable row, the exact row is read back, synthetic evidence is cleaned up, and the live service remains healthy.
Pitfalls
- Calling
mailto:a submitted form. - Using local SQLite inside an ephemeral function.
- Trusting browser CORS to stop non-browser clients.
- Trusting
CF-Connecting-IPorX-Forwarded-Fordirectly in the app. - Counting only inserted rows for rate limiting, so duplicates bypass the limit.
- Promising 90-day deletion when cleanup runs only on writes.
- Reporting proxy reload success without reading the public HTTPS endpoint.
- Keeping synthetic production leads after verification.
04 同仓库更多 Skills
writing-for-agents
Use for delegate_task, Kanban, and all agent-facing text.
why
Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
vue-best-practices
Use for Vue 3, .vue files, Vue Router, or Pinia. Skip when the repo has no Vue.
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
tailwind-v4
Use when writing or reviewing Tailwind CSS v4 classes or migrating v3 syntax.
react-best-practices
Mastra React subset only. Generic React or Next uses vercel-react-best-practices.