FormSeal Admin Sync - Project overview

FormSeal Admin Sync is a separate, administrator-operated system used to retrieve encrypted submissions from FormSeal and process them securely on the administrator’s local machine.

It exists to complete FormSeal’s trust model: the backend remains blind, while administrators retain full control over data access and decryption.

Overview

Purpose

Provide a controlled mechanism for administrators to export encrypted submissions and recover plaintext locally, without weakening FormSeal’s security guarantees.

Scope

Admin Sync is not part of the public submission flow. It is explicitly designed for trusted operators running tools on their own machines.

Core stack

Cloudflare Pages Functions · KV Storage · Local Python tooling · libsodium / NaCl · Stateless, token-based export APIs

Relationship to FormSeal

FormSeal handles ingestion and storage. Admin Sync handles export, decryption, and offline processing.

High-level flow

Export request: An administrator initiates an authenticated export request via a protected API endpoint.
Encrypted stream: The backend issues a short-lived, single-use token and streams encrypted submissions from KV storage.
Local processing: Exported data is decrypted, deduplicated, and structured locally using administrator-held private keys.

Backend export API

Deployment model: Export endpoints are deployed alongside FormSeal’s public APIs using Cloudflare Pages Functions, preserving a same-origin design.
Access control: Export requests require explicit administrator authentication and issue short-lived, identity-bound export tokens.
Data handling: The backend never decrypts messages and only streams encrypted blobs as opaque data.

Local admin tooling

Execution model

Tools are run locally on the administrator’s machine and can be invoked individually or as a coordinated workflow.

Cryptographic boundary

Private keys exist only on the local system. No secrets are transmitted to or stored by the backend.

Data lifecycle

Decrypted messages are written to local, append-only data stores with built-in replay and duplicate detection.

Orchestration model

A lightweight orchestrator script coordinates the export, decryption, and cleanup steps, while preserving the ability to run each tool manually.

This approach prioritizes transparency, debuggability, and operator control over opaque automation.

Trust boundaries

Public users

Can only submit encrypted form data through FormSeal’s browser-side pipeline.

Backend

Stores and exports encrypted blobs only, without access to plaintext or private keys.

Administrator

Holds decryption keys locally and performs all recovery and inspection offline.

Possible future changes

Removal of the browser-based admin workflow, which is currently incomplete and introduces unnecessary attack surface.
Continued hardening of the local, automated admin workflow based on long-lived secrets and controlled execution environments.
Development of a dedicated CLI or lightweight UI renderer for locally decrypted inbox data, replacing direct inspection of raw JSONL files.
Improvements to operational ergonomics, error reporting, and auditability within the admin tooling.

Links

FormSeal (core project): Project overview

Admin Sync repository: github.com/grayguava/formseal-sync