@formseal/embed 3.1.0

package/README.md

@@ -0,0 +1,172 @@
+<p align="center">
+  <img src="fse-ascii.png" alt="formseal">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/encryption-X25519-10b981?style=flat-square&labelColor=1e293b&borderRadius=6px">
+  <img src="https://img.shields.io/badge/decryption-offline%20only-f59e0b?style=flat-square&labelColor=1e293b&borderRadius=6px">
+  <img src="https://img.shields.io/badge/backend-blind-6366f1?style=flat-square&labelColor=1e293b&borderRadius=6px">
+  <img src="https://img.shields.io/npm/v/@formseal/embed?style=flat-square&label=npm&labelColor=fff&color=cb0000&borderRadius=6px">
+  <img src="https://img.shields.io/badge/license-MIT-fc8181?style=flat-square&labelColor=1e293b&borderRadius=6px">
+</p>
+
+<p align="center">
+  A server-blind, browser-native encrypted form poster.
+</p>
+
+---
+
+Form submissions are encrypted in the browser using X25519 sealed boxes before reaching any endpoint. The backend receives and stores opaque ciphertext only. Decryption is operator-controlled and happens offline, with your private key.
+
+formseal is not a hosted service, dashboard, or SaaS product. It is a drop-in client-side utility.
+
+---
+
+## Installation
+
+```bash
+npm install -g @formseal/embed
+fse init
+```
+
+Scaffolds `./formseal-embed/` into your project, then:
+
+```bash
+fse configure quick
+```
+
+You'll be prompted for your POST endpoint and public key. See [Getting started](./docs/getting-started.md) for key generation.
+
+> If you prefer not to install globally, `npx @formseal/embed init` works — but you'll need to edit `fse.config.js` manually instead of using the CLI.
+
+---
+
+## Security guarantee
+
+> If the POST 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.
+
+---
+
+## Threat model
+
+formseal is for environments where:
+
+- The hosting provider or backend may be compromised
+- The backend must be treated as hostile
+- Data seizure is a realistic concern
+- Retroactive disclosure must be prevented
+
+The priority is **backward confidentiality** — protecting already-submitted data — not convenience or real-time administration.
+
+---
+
+## How it works
+
+On submit, formseal:
+
+1. Collects field values from your form by `name` attribute
+2. Validates them against your field rules
+3. Seals the payload with `crypto_box_seal` (Curve25519 + XSalsa20-Poly1305)
+4. POSTs raw ciphertext to your configured endpoint
+
+Your endpoint stores the ciphertext. Only the holder of the private key can decrypt it.
+
+---
+
+## Wire up your HTML
+
+```html
+<form id="contact-form">
+
+  <!-- honeypot — hide off-screen with CSS -->
+  <input type="text" name="_hp" tabindex="-1" autocomplete="off"
+    style="position:absolute;left:-9999px;opacity:0;height:0;">
+
+  <input type="text"  name="name">
+  <span data-fse-error="name"></span>
+
+  <input type="email" name="email">
+  <span data-fse-error="email"></span>
+
+  <textarea name="message"></textarea>
+  <span data-fse-error="message"></span>
+
+  <button type="submit" id="contact-submit">Send message</button>
+</form>
+
+<div id="contact-status"></div>
+
+<script>
+  window.fseCallbacks = {
+    onSuccess: function(response) {},
+    onError:   function(error)    {},
+  };
+</script>
+
+<script src="/formseal-embed/globals.js"></script>
+```
+
+---
+
+## Payload format
+
+```json
+{
+  "version": "fse.v1.0",
+  "origin": "contact-form",
+  "id": "<uuid>",
+  "submitted_at": "<iso8601>",
+  "client_tz": "Europe/London",
+  "data": {
+    "name": "...",
+    "email": "...",
+    "message": "..."
+  }
+}
+```
+
+The entire object is sealed with `crypto_box_seal`. Your endpoint receives raw ciphertext as the request body.
+
+---
+
+## 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 does not do
+
+- No admin dashboard or inbox UI
+- No hosted service
+- No bundler or build step required
+- No npm dependencies at runtime
+
+These are intentional.
+
+---
+
+## Documentation
+
+- [Getting started](./docs/getting-started.md)
+- [Concepts → How it works](./docs/concepts/how-it-works.md)
+- [Concepts → Security](./docs/concepts/security.md)
+- [Integration → HTML](./docs/integration/html.md)
+- [Integration → Fields](./docs/integration/fields.md)
+- [Integration → JavaScript](./docs/integration/javascript.md)
+- [Deployment → Endpoint](./docs/deployment/endpoint.md)
+- [Deployment → Decryption](./docs/deployment/decryption.md)
+- [Deployment → Versioning](./docs/deployment/versioning.md)
+
+---
+
+## License
+
+MIT

package/cli/commands/about.py

@@ -0,0 +1,24 @@
+# commands/about.py
+# About command - shows logo and info
+
+from ui.output import br, link, O, R, W, D
+from logo import LOGO
+
+
+def run():
+    br()
+    lines = LOGO.strip().split("\n")
+    for i, line in enumerate(lines):
+        if i == 0:
+            line = " " + line  # add leading space to first line
+        print(f"{O}{line}{R}")
+    br()
+    print(f"  {W}Client-side encrypted contact forms.{R}")
+    br()
+    print(f"  {D}Author:{R} grayguava")
+    print(f"  {D}License:{R} MIT")
+    br()
+    print(f"  {D}GitHub links:")
+    link("https://github.com/grayguava/formseal-embed")
+    link("https://github.com/grayguava/formseal-embed/docs")
+    br()

package/cli/commands/configure.py

@@ -0,0 +1,292 @@
+# commands/configure.py
+# Configure formseal-embed settings.
+# Usage:
+#   fse configure quick        - set endpoint + key
+#   fse configure field add <name> [options]
+#   fse configure field remove <name>
+#   fse configure field required <name> <true|false>
+#   fse configure field maxLength <name> <number>
+#   fse configure field type <name> <email|tel|text>
+
+import re
+import json
+from pathlib import Path
+
+from ui.output import br, rule, row, code, fail, C, G, Y, S, W, R, D
+
+CONFIG_PATH = Path.cwd() / "formseal-embed" / "config" / "fse.config.js"
+
+MARKERS = {
+    "endpoint":   "endpoint:",
+    "publicKey":  "publicKey:",
+}
+
+
+def _prompt(label: str, hint: str) -> str:
+    try:
+        return input(f"  {D}{label}:{R} ").strip()
+    except (KeyboardInterrupt, EOFError):
+        br()
+        return ""
+
+
+def _patch(field: str, value: str):
+    marker = MARKERS.get(field)
+    if not marker or not value:
+        return False
+
+    if not CONFIG_PATH.exists():
+        return False
+
+    lines   = CONFIG_PATH.read_text(encoding="utf-8").splitlines(keepends=True)
+    matched = False
+    updated = []
+
+    for line in lines:
+        if marker in line and "://" not in marker:
+            matched = True
+            line    = re.sub(r':\s*"[^"]*"', f': "{value}"', line)
+        updated.append(line)
+
+    if matched:
+        CONFIG_PATH.write_text("".join(updated), encoding="utf-8")
+    return matched
+
+
+def _normalize_endpoint(url: str) -> str:
+    url = url.strip()
+    if not url.startswith("http://") and not url.startswith("https://"):
+        url = "https://" + url
+    return url
+
+
+def _load_config() -> dict:
+    if not CONFIG_PATH.exists():
+        return {}
+    content = CONFIG_PATH.read_text(encoding="utf-8")
+    match = re.search(r'var FSE = (\{[\s\S]*?\});', content)
+    if not match:
+        return {}
+    try:
+        return json.loads(match.group(1))
+    except json.JSONDecodeError:
+        return {}
+
+
+def _save_config(cfg: dict):
+    lines = CONFIG_PATH.read_text(encoding="utf-8").splitlines(keepends=True)
+    out = []
+    for line in lines:
+        if line.strip().startswith("fields:") and "{" in line:
+            out.append(line)
+            break
+        out.append(line)
+    else:
+        out.append(f"  fields: {json.dumps(cfg.get('fields', {}), indent=4)},\n")
+        CONFIG_PATH.write_text("".join(out), encoding="utf-8")
+        return
+
+    indent = "  "
+    fields_json = json.dumps(cfg.get("fields", {}), indent=4)
+    fields_json = "\n".join(indent + line for line in fields_json.splitlines())
+    out.append(fields_json + ",\n")
+
+    while lines and not lines[-1].strip().startswith("}"):
+        lines.pop()
+    out.extend(lines)
+
+    CONFIG_PATH.write_text("".join(out), encoding="utf-8")
+
+
+def run(subcommand: str, args: list):
+    if not subcommand:
+        fail("Usage: fse configure <quick|field>")
+
+    if not CONFIG_PATH.exists():
+        fail(
+            "formseal-embed/config/fse.config.js not found.\n"
+            f"           Run {W}fse init{R} first."
+        )
+
+    if subcommand in ("quick", "q"):
+        _run_quick()
+    elif subcommand in ("field", "fields", "f"):
+        _run_field(args)
+    else:
+        fail(f"Unknown subcommand: {subcommand}\n" +
+             f"           Use {W}fse configure quick{R} or {W}fse configure field{R}")
+
+
+def _run_quick():
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-embed{R}  {G}quick configure{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+
+    endpoint = _prompt("POST endpoint", ":")
+    key      = _prompt("X25519 public key (base64url)", ":")
+
+    br()
+    updated = False
+    if endpoint:
+        endpoint = _normalize_endpoint(endpoint)
+        if _patch("endpoint", endpoint):
+            updated = True
+    if key:
+        if _patch("publicKey", key):
+            updated = True
+
+    if updated:
+        print(f"  {S}*{R} {G}Updated!{R}")
+        print(G + " " + "\u2500" * 52 + R)
+        
+        if endpoint:
+            row(">", "POST API", endpoint)
+        if key:
+            row(">", "X25519 Key", key[:24] + "..." if len(key) > 24 else key)
+
+
+def _run_field(args: list):
+    if not args:
+        fail("Usage: fse configure field <add|remove|required|maxLength|type>")
+
+    action = args[0]
+
+    if action == "add":
+        _field_add(args[1:])
+    elif action in ("remove", "rm", "delete"):
+        _field_remove(args[1:])
+    elif action == "required":
+        _field_required(args[1:])
+    elif action in ("maxlength", "maxLength"):
+        _field_maxlength(args[1:])
+    elif action in ("type",):
+        _field_type(args[1:])
+    else:
+        fail(f"Unknown field action: {action}\n" +
+             f"           Use add, remove, required, maxLength, or type")
+
+
+def _field_add(args: list):
+    if not args:
+        fail("Usage: fse configure field add <name> [required:true] [maxLength:n] [type:email]")
+
+    name = args[0]
+    cfg = _load_config()
+    fields = cfg.get("fields", {})
+
+    if name in fields:
+        fail(f"Field {W}{name}{R} already exists.")
+
+    field = {}
+    for opt in args[1:]:
+        if ":" in opt:
+            k, v = opt.split(":", 1)
+            if k == "required":
+                field["required"] = v.lower() == "true"
+            elif k in ("maxLength", "maxlength"):
+                try:
+                    field["maxLength"] = int(v)
+                except ValueError:
+                    fail(f"Invalid maxLength: {v}")
+            elif k in ("type",):
+                if v not in ("email", "tel", "text"):
+                    fail(f"Invalid type: {v}. Use email, tel, or text.")
+                field["type"] = v
+
+    fields[name] = field
+    cfg["fields"] = fields
+    _save_config(cfg)
+
+    br()
+    print(f"  {G}Added field:{R} {name}")
+    if field:
+        for k, v in field.items():
+            row("", k, str(v))
+
+
+def _field_remove(args: list):
+    if not args:
+        fail("Usage: fse configure field remove <name>")
+
+    name = args[0]
+    cfg = _load_config()
+    fields = cfg.get("fields", {})
+
+    if name not in fields:
+        fail(f"Field {W}{name}{R} not found.")
+
+    del fields[name]
+    cfg["fields"] = fields
+    _save_config(cfg)
+
+    br()
+    print(f"  {G}Removed field:{R} {name}")
+
+
+def _field_required(args: list):
+    if len(args) != 2:
+        fail("Usage: fse configure field required <name> <true|false>")
+
+    name, value = args
+    if value not in ("true", "false"):
+        fail("Use true or false")
+
+    cfg = _load_config()
+    fields = cfg.get("fields", {})
+
+    if name not in fields:
+        fail(f"Field {W}{name}{R} not found.")
+
+    fields[name]["required"] = value == "true"
+    cfg["fields"] = fields
+    _save_config(cfg)
+
+    br()
+    row(">", f"{name}.required", value)
+
+
+def _field_maxlength(args: list):
+    if len(args) != 2:
+        fail("Usage: fse configure field maxLength <name> <number>")
+
+    name, value = args
+    try:
+        maxlen = int(value)
+    except ValueError:
+        fail(f"Invalid number: {value}")
+
+    cfg = _load_config()
+    fields = cfg.get("fields", {})
+
+    if name not in fields:
+        fail(f"Field {W}{name}{R} not found.")
+
+    fields[name]["maxLength"] = maxlen
+    cfg["fields"] = fields
+    _save_config(cfg)
+
+    br()
+    row(">", f"{name}.maxLength", str(maxlen))
+
+
+def _field_type(args: list):
+    if len(args) != 2:
+        fail("Usage: fse configure field type <name> <email|tel|text>")
+
+    name, value = args
+    if value not in ("email", "tel", "text"):
+        fail(f"Invalid type: {value}. Use email, tel, or text.")
+
+    cfg = _load_config()
+    fields = cfg.get("fields", {})
+
+    if name not in fields:
+        fail(f"Field {W}{name}{R} not found.")
+
+    fields[name]["type"] = value
+    cfg["fields"] = fields
+    _save_config(cfg)
+
+    br()
+    row(">", f"{name}.type", value)

package/cli/commands/help.py

@@ -0,0 +1,29 @@
+# commands/help.py
+# Help command - shows all available commands
+
+from ui.output import br, rule, cmd_line, link, C, G, Y, M, W, D, R
+
+
+def run():
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-embed{R}  {G}@formseal/embed{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    print(f"  {G}>>{R} {Y}Commands{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    cmd_line("fse init",                "scaffold ./formseal-embed/ into current directory")
+    cmd_line("fse configure quick",      "set endpoint and public key")
+    cmd_line("fse configure field add",    "add a field")
+    cmd_line("fse configure field remove", "remove a field")
+    cmd_line("fse configure field required", "set field required")
+    cmd_line("fse configure field maxLength", "set field max length")
+    cmd_line("fse configure field type", "set field type (email|tel|text)")
+    br()
+    print(f"  {G}>>{R} {M}coming soon{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    cmd_line("fse doctor",              "validate config and schema")
+    br()
+    print(f"  {G}>>{R} {Y}docs{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    print(f"  {G}Docs:{R}")
+    link("https://github.com/grayguava/formseal-embed/docs")
+    br()

package/cli/commands/init.py

@@ -0,0 +1,119 @@
+# commands/init.py
+# Scaffolds ./formseal-embed/ into the current working directory.
+# After scaffolding, prompts for endpoint and public key (both skippable).
+
+import shutil
+from pathlib import Path
+
+from ui.output import br, rule, row, code, link, fail, C, G, Y, S, W, R, D
+
+# MASCOT: from ui.mascot import on_init
+
+SRC  = Path(__file__).resolve().parent.parent.parent / "src"
+DEST = Path.cwd() / "formseal-embed"
+
+
+def _prompt(label: str, hint: str) -> str:
+    try:
+        return input(f"  {D}{label}:{R} ").strip()
+    except (KeyboardInterrupt, EOFError):
+        br()
+        return ""
+
+
+def _confirm(prompt: str) -> bool:
+    try:
+        return input(f"  {W}{prompt}{R} ").strip().lower() == "y"
+    except (KeyboardInterrupt, EOFError):
+        br()
+        return False
+
+
+def _patch_config(field: str, value: str):
+    import re
+    from commands.configure import MARKERS
+
+    marker = MARKERS.get(field)
+    if not marker or not value:
+        return False
+
+    config = DEST / "config" / "fse.config.js"
+    if not config.exists():
+        return False
+
+    lines   = config.read_text(encoding="utf-8").splitlines(keepends=True)
+    updated = []
+    matched = False
+    for line in lines:
+        if marker in line and "://" not in marker:
+            matched = True
+            line = re.sub(r':\s*"[^"]*"', f': "{value}"', line)
+        updated.append(line)
+    
+    if matched:
+        config.write_text("".join(updated), encoding="utf-8")
+    return matched
+
+
+def _normalize_endpoint(url: str) -> str:
+    url = url.strip()
+    if not url.startswith("http://") and not url.startswith("https://"):
+        url = "https://" + url
+    return url
+
+
+def run():
+    if DEST.exists():
+        fail(
+            "./formseal-embed/ already exists.\n"
+            "           Remove it first if you want a fresh scaffold."
+        )
+
+    if not SRC.exists():
+        fail(
+            f"Source files not found at {SRC}.\n"
+            "           Is the package installed correctly?"
+        )
+
+    shutil.copytree(SRC, DEST)
+
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-embed{R}  {S}initialized{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+
+    do_config = _confirm("Configure now?")
+    
+    if do_config:
+        br()
+        endpoint = _prompt("POST endpoint", "https://your-api.example.com/submit")
+        key      = _prompt("X25519 public key (base64url)", "base64url x25519 public key")
+
+        br()
+        updated = False
+        if endpoint:
+            endpoint = _normalize_endpoint(endpoint)
+            if _patch_config("endpoint", endpoint):
+                updated = True
+        if key:
+            if _patch_config("publicKey", key):
+                updated = True
+
+        if updated:
+            print(f"  {S}*{R} {G}Set!{R}")
+            print(G + " " + "\u2500" * 52 + R)
+            
+            if endpoint:
+                row(">", "POST API", endpoint)
+            if key:
+                row(">", "X25519 Key", key[:24] + "..." if len(key) > 24 else key)
+        
+        br()
+
+    br()
+    print(f"  {G}\u2192{R} {Y}Next steps{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+    print(f"  {G}Wire up in your HTML:{R}")
+    code('<script src="/formseal-embed/globals.js"></script>')
+    br()