@formseal/embed 3.1.0

package/cli/fse.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+# fse.py
+# Entry point. Parses args and routes to the correct command.
+# Adding a new command:
+#   1. Create commands/newcommand.py with a run() function
+#   2. Import it below
+#   3. Add a case to the router
+
+import sys
+import os
+
+if os.name == "nt":
+    try:
+        os.system("chcp 65001 >nul")
+    except:
+        pass
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+except:
+    pass
+
+sys.path.insert(0, os.path.dirname(__file__))
+
+from ui.output import br, rule, cmd_line, link, fail, badge, C, G, Y, M, W, D, R, BOLD
+from logo import LOGO
+
+from commands import init as cmd_init
+from commands import configure as cmd_configure
+from commands import help as cmd_help
+from commands import about as cmd_about
+
+
+# -- intro --
+
+def intro():
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-embed{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+    print(f"  {G}Start:{R}")
+    br()
+    print(f"  {W}fse init{R}")
+    print(f"  {D}scaffold project files{R}")
+    br()
+    print(f"  {W}fse configure quick{R}")
+    print(f"  {D}set endpoint + key{R}")
+    br()
+    print(f"  {G}Help:{R}")
+    br()
+    print(f"  {W}fse --help{R}")
+    link("https://github.com/grayguava/formseal-embed/docs")
+    br()
+
+
+# -- router --
+
+def main():
+    args    = sys.argv[1:]
+    command = args[0] if args else None
+
+    match command:
+        case "init":
+            cmd_init.run()
+
+        case "configure":
+            sub = args[1] if len(args) > 1 else None
+            cmd_configure.run(sub, args[2:])
+
+        case "doctor":
+            fail("fse doctor is not yet available.")
+
+        case None | "fse":
+            intro()
+
+        case "--help" | "-h":
+            cmd_help.run()
+
+        case "--about":
+            cmd_about.run()
+
+        case _:
+            fail(
+                f"Unknown command: {command}\n"
+                f"           Run {W}fse --help{R} for usage."
+            )
+
+
+if __name__ == "__main__":
+    main()

package/cli/logo.py

@@ -0,0 +1,11 @@
+# cli/logo.py
+# ASCII art logo - edit this file to change the banner
+
+LOGO = """
+  _____                                         .__                          ___.              .___
+_╱ ____╲___________  _____   ______ ____ _____  │  │             ____   _____╲_ │__   ____   __│ _╱
+╲   __╲╱  _ ╲_  __ ╲╱     ╲ ╱  ___╱╱ __ ╲╲__  ╲ │  │    ______ _╱ __ ╲ ╱     ╲│ __ ╲_╱ __ ╲ ╱ __ │ 
+ │  │ (  <_> )  │ ╲╱  Y Y  ╲╲___ ╲╲  ___╱ ╱ __ ╲│  │__ ╱_____╱ ╲  ___╱│  Y Y  ╲ ╲_╲ ╲  ___╱╱ ╱_╱ │ 
+ │__│  ╲____╱│__│  │__│_│  ╱____  >╲___  >____  ╱____╱          ╲___  >__│_│  ╱___  ╱╲___  >____ │ 
+                         ╲╱     ╲╱     ╲╱     ╲╱                    ╲╱      ╲╱    ╲╱     ╲╱     ╲╱ 
+"""

package/cli/shim.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path          = require("path");
+
+const MIN_MAJOR = 3;
+const MIN_MINOR = 8;
+
+const SCRIPT = path.join(__dirname, "fse.py");
+const ARGS   = process.argv.slice(2);
+
+function findPython() {
+  const candidates = ["py", "python", "python3"];
+
+  for (const cmd of candidates) {
+    const result = spawnSync(cmd, ["--version"], { encoding: "utf8" });
+    if (result.status === 0) {
+      const output = (result.stdout || result.stderr || "").trim();
+      const match  = output.match(/Python (\d+)\.(\d+)/);
+      if (match) {
+        const major = parseInt(match[1], 10);
+        const minor = parseInt(match[2], 10);
+        if (major === MIN_MAJOR && minor >= MIN_MINOR) return { cmd, version: output };
+        if (major > MIN_MAJOR) return { cmd, version: output };
+        fail(
+          "Python " + MIN_MAJOR + "." + MIN_MINOR + "+ is required.\n" +
+          "           Found: " + output + "\n" +
+          "           Install from https://python.org"
+        );
+      }
+    }
+  }
+  return null;
+}
+
+function fail(msg) {
+  console.error("\x1b[31m\x1b[1m ERR \x1b[0m " + msg);
+  process.exit(1);
+}
+
+const python = findPython();
+
+if (!python) {
+  fail(
+    "Python is required to run fse.\n" +
+    "           Install from https://python.org\n" +
+    "           Windows: winget install Python.Python.3"
+  );
+}
+
+const result = spawnSync(python.cmd, [SCRIPT, ...ARGS], {
+  stdio: "inherit",
+  env:   process.env,
+});
+
+process.exit(result.status ?? 1);

package/cli/ui/output.py

@@ -0,0 +1,79 @@
+# ui/output.py
+# All terminal output primitives. No logic, no commands.
+# Every print in fse goes through here.
+
+import os
+import sys
+
+if os.name == "nt":
+    try:
+        os.system("chcp 65001 >nul")
+    except:
+        pass
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+except:
+    pass
+
+# -- ansi colors --
+
+RESET  = "\x1b[0m"
+BOLD   = "\x1b[1m"
+DIM    = "\x1b[2m"
+
+RED    = "\x1b[31m"
+GREEN  = "\x1b[32m"
+YELLOW = "\x1b[33m"
+BLUE   = "\x1b[34m"
+MAGENTA= "\x1b[35m"
+CYAN   = "\x1b[36m"
+WHITE  = "\x1b[37m"
+GRAY   = "\x1b[90m"
+
+# Semantic palette
+B = "\x1b[38;5;109m"  # muted green - arguments/placeholders
+C = "\x1b[38;5;117m"  # soft cyan - title, links, script tag
+M = "\x1b[38;5;141m"  # muted magenta - experimental sections
+G = "\x1b[38;5;244m"  # dim gray - descriptions
+Y = "\x1b[38;5;103m"  # muted purple - section headers
+S = "\x1b[38;5;112m"  # soft green - success states
+O = "\x1b[38;5;130m"  # dim orange - logo
+W = WHITE + BOLD      # bright white - commands
+D = DIM              # dim - secondary
+R = RESET            # reset
+
+
+# -- primitives --
+
+def br():
+    print()
+
+def rule():
+    print(G + " " + "\u2500" * 52 + R)
+
+def badge(label, color):
+    return f"{color}{BOLD} {label} {R}"
+
+def fail(msg):
+    br()
+    print(f"{badge('ERR', RED)} {msg}")
+    br()
+    raise SystemExit(1)
+
+def row(icon, label, value):
+    pad   = 10
+    label = (label + " " * pad)[:pad]
+    print(f"{S}{icon}{R}  {D}{label}{R}  {W}{value}{R}")
+
+def cmd_line(command, desc):
+    pad     = 34
+    command = (command + " " * pad)[:pad]
+    print(f"  {W}{command}{R}{G}{desc}{R}")
+
+def code(msg):
+    print(f"  {C}{msg}{R}")
+
+def link(msg):
+    print(f"  {C}{msg}{R}")

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@formseal/embed",
+  "description": "Drop-in client-side encrypted contact form.",
+  "license": "MIT",
+  "bin": {
+    "fse": "./cli/shim.js"
+  },
+  "files": [
+    "src/",
+    "cli/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "formseal",
+    "fsembed",
+    "fse",
+    "encryption",
+    "curve25519",
+    "contact-form",
+    "libsodium",
+    "privacy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grayguava/formseal-embed.git"
+  },
+  "version": "3.1.0"
+}

package/src/config/fse.config.js

@@ -0,0 +1,69 @@
+// fse.config.js
+// Unified configuration for formseal-embed.
+//
+// Edit this file or use the CLI:
+//   fse configure endpoint <url>
+//   fse configure key <base64url>
+//   fse configure field add <name> [options]
+//   fse configure field remove <name>
+//   fse configure field required <name> <true|false>
+//   fse configure field maxLength <name> <number>
+
+var FSE = {
+
+  // -- Endpoint --
+  // POST target. Receives: { ciphertext: "<base64url>" }
+  endpoint: "https://your-api.example.com/submit",
+
+  // -- Origin --
+  // Identifier for this form deployment. Useful when you have multiple forms.
+  origin: "contact-form",
+
+  // -- Encryption --
+  // Recipient x25519 public key in base64url (32 bytes)
+  publicKey: "PASTE_YOUR_BASE64URL_PUBLIC_KEY_HERE",
+
+  // -- Form selectors --
+  form:   "#contact-form",
+  submit: "#contact-submit",
+  status: "#contact-status",
+
+  // -- Submit button states --
+  submitStates: {
+    idle:    "Send message",
+    sending: "Sending...",
+    sent:    "Sent",
+  },
+
+  // -- Success behaviour --
+  onSuccess: {
+    redirect:    false,
+    redirectUrl: "/thank-you",
+    message:     "Thanks! Your message has been sent.",
+  },
+
+  // -- Error behaviour --
+  onError: {
+    message: "Something went wrong. Please try again.",
+  },
+
+  // -- Fields --
+  // Key = field name (matches [name] attribute in HTML)
+  // Value = validation rules
+  fields: {
+    name: {
+      required:  true,
+      maxLength: 100,
+    },
+    email: {
+      type:      "email",
+      required:  true,
+      maxLength: 200,
+    },
+    message: {
+      required:  true,
+      maxLength: 1000,
+    },
+  },
+
+};

package/src/globals.js

@@ -0,0 +1,75 @@
+// globals.js
+// Single entry point. Drop this one script tag in your HTML.
+//
+// Usage:
+//   <script src="formseal-embed/globals.js"></script>
+
+(function () {
+  "use strict";
+
+  var scripts = document.querySelectorAll("script[src]");
+  var selfSrc = "";
+  for (var i = 0; i < scripts.length; i++) {
+    if (scripts[i].src.indexOf("globals.js") !== -1) {
+      selfSrc = scripts[i].src;
+      break;
+    }
+  }
+  var base = selfSrc.substring(0, selfSrc.lastIndexOf("/") + 1);
+
+  var FILES = [
+    "vendor/sodium.js",
+    "config/fse.config.js",
+    "runtime/fse.crypto.js",
+    "runtime/fse.payload.js",
+    "runtime/fse.validate.js",
+    "runtime/fse.form.js",
+  ];
+
+  function loadNext(index) {
+    if (index >= FILES.length) {
+      try {
+        sodium.ready.then(function () {
+          try {
+            FSEForm.mount();
+          } catch (err) {
+            console.error("[fse] Mount failed:", err);
+          }
+        }).catch(function (err) {
+          console.error("[fse] sodium.ready failed:", err);
+        });
+      } catch (err) {
+        console.error("[fse] sodium is not available:", err);
+      }
+      return;
+    }
+
+    var url = base + FILES[index];
+
+    fetch(url)
+      .then(function (res) {
+        if (!res.ok) {
+          console.error("[fse] " + res.status + " loading " + url + ". Aborting.");
+          return null;
+        }
+        return res.text();
+      })
+      .then(function (code) {
+        if (code === null || code === undefined) return;
+        var s = document.createElement("script");
+        s.textContent = code;
+        document.head.appendChild(s);
+        loadNext(index + 1);
+      })
+      .catch(function (err) {
+        console.error("[fse] Failed to load " + url + ":", err);
+      });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", function () { loadNext(0); });
+  } else {
+    loadNext(0);
+  }
+
+})();

package/src/runtime/fse.crypto.js

@@ -0,0 +1,59 @@
+// fse.crypto.js
+// Pure crypto utilities. No DOM access. No config dependencies.
+// Depends on: window.sodium (libsodium-wrappers, must be ready)
+
+var FSECrypto = (function () {
+
+  // -- Encoding helpers --
+
+  function bytesToBase64url(bytes) {
+    return btoa(String.fromCharCode(...bytes))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+  }
+
+  function base64urlToBytes(b64url) {
+    b64url = b64url.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = b64url.length % 4;
+    if (pad) b64url += "=".repeat(4 - pad);
+    const binary = atob(b64url);
+    return Uint8Array.from(binary, function (c) { return c.charCodeAt(0); });
+  }
+
+  // -- Encryption --
+
+  // Seals a JS object as JSON to a recipient's x25519 public key.
+  // Returns the ciphertext as a base64url string.
+  // recipientPublicKey: base64url-encoded x25519 public key (32 bytes).
+  async function sealJSON(obj, publicKey) {
+    if (!publicKey) {
+      throw new Error(
+        "[fse/crypto] publicKey is not set in fse.config.js."
+      );
+    }
+
+    await sodium.ready;
+
+    const pubKey = base64urlToBytes(publicKey);
+    if (pubKey.length !== 32) {
+      throw new Error(
+        "[fse/crypto] publicKey must decode to exactly 32 bytes."
+      );
+    }
+
+    const plaintext  = new TextEncoder().encode(JSON.stringify(obj));
+    const ciphertext = sodium.crypto_box_seal(plaintext, pubKey);
+
+    return bytesToBase64url(ciphertext);
+  }
+
+  // -- Public API --
+
+  return {
+    sealJSON,
+    bytesToBase64url,
+    base64urlToBytes,
+  };
+
+})();

package/src/runtime/fse.form.js

@@ -0,0 +1,181 @@
+// fse.form.js
+// Submit pipeline controller. Touches the DOM only for:
+//   - reading field values (by name attribute)
+//   - managing submit button state
+//   - writing validation errors to [data-fse-error="fieldname"] elements
+//   - writing status messages to the statusSelector element
+//
+// The dev owns all form markup. Formseal-embed owns none of it.
+//
+// Depends on: FSE, FSECrypto, FSEPayload, FSEValidate (all globals).
+
+var FSEForm = (function () {
+
+  function requireGlobal(name) {
+    if (typeof window[name] === "undefined") {
+      throw new Error("[fse/form] " + name + " is not defined.");
+    }
+    return window[name];
+  }
+
+  function collectData(formEl, fields) {
+    var data = {};
+    Object.keys(fields).forEach(function (name) {
+      var input = formEl.querySelector("[name='" + name + "']");
+      if (!input) return;
+      data[name] = input.value.trim();
+    });
+    return data;
+  }
+
+  function clearFieldErrors(fields) {
+    Object.keys(fields).forEach(function (name) {
+      var el = document.querySelector("[data-fse-error='" + name + "']");
+      if (el) el.textContent = "";
+      var input = document.querySelector("[name='" + name + "']");
+      if (input) input.removeAttribute("aria-invalid");
+    });
+  }
+
+  function showFieldErrors(errors) {
+    var focused = false;
+    errors.forEach(function (err) {
+      var el    = document.querySelector("[data-fse-error='" + err.name + "']");
+      var input = document.querySelector("[name='" + err.name + "']");
+      if (el) el.textContent = err.message;
+      if (input) {
+        input.setAttribute("aria-invalid", "true");
+        if (!focused) { input.focus(); focused = true; }
+      }
+    });
+  }
+
+  function setStatus(cfg, message, isError, responseData) {
+    if (cfg.status) {
+      var el = document.querySelector(cfg.status);
+      if (el) {
+        el.textContent = message;
+        el.setAttribute("data-fse-status", isError ? "error" : "success");
+      }
+    }
+
+    var cb = window.fseCallbacks;
+    if (cb) {
+      if (!isError && typeof cb.onSuccess === "function") {
+        cb.onSuccess(responseData);
+      }
+      if (isError && typeof cb.onError === "function") {
+        cb.onError(new Error(message));
+      }
+    }
+  }
+
+  function clearStatus(cfg) {
+    if (cfg.status) {
+      var el = document.querySelector(cfg.status);
+      if (el) {
+        el.textContent = "";
+        el.removeAttribute("data-fse-status");
+      }
+    }
+  }
+
+  function setButtonState(btn, state, cfg) {
+    var states = cfg.submitStates || {};
+    switch (state) {
+      case "sending":
+        btn.disabled    = true;
+        btn.textContent = states.sending || "Sending...";
+        break;
+      case "sent":
+        btn.disabled    = true;
+        btn.textContent = states.sent || "Sent";
+        break;
+      case "idle":
+      default:
+        btn.disabled    = false;
+        btn.textContent = states.idle || "Send";
+        break;
+    }
+  }
+
+  function mount() {
+    var cfg    = requireGlobal("FSE");
+    var fields = cfg.fields || {};
+
+    var formEl = document.querySelector(cfg.form);
+    if (!formEl) {
+      console.error("[fse/form] Form not found: " + cfg.form);
+      return;
+    }
+
+    var submitBtn = document.querySelector(cfg.submit);
+    if (!submitBtn) {
+      console.error("[fse/form] Submit button not found: " + cfg.submit);
+      return;
+    }
+
+    setButtonState(submitBtn, "idle", cfg);
+
+    formEl.addEventListener("submit", async function (e) {
+      e.preventDefault();
+
+      var hp = formEl.querySelector("[name='_hp']");
+      if (hp && hp.value) return;
+
+      clearFieldErrors(fields);
+      clearStatus(cfg);
+
+      var data = collectData(formEl, fields);
+
+      var result = FSEValidate.validate(data);
+      if (!result.valid) {
+        showFieldErrors(result.errors);
+        return;
+      }
+
+      setButtonState(submitBtn, "sending", cfg);
+
+      try {
+        var payload = FSEPayload.build(data);
+
+        var ciphertext = await FSECrypto.sealJSON(
+          payload,
+          cfg.publicKey
+        );
+
+        var res = await fetch(cfg.endpoint, {
+          method:      "POST",
+          headers:    { "Content-Type": "text/plain" },
+          credentials: "omit",
+          body:       ciphertext,
+        });
+
+        if (!res.ok) {
+          throw new Error("Server responded with " + res.status);
+        }
+
+        var responseData = await res.json().catch(function () { return {}; });
+
+        setButtonState(submitBtn, "sent", cfg);
+        formEl.reset();
+
+        if (cfg.onSuccess.redirect) {
+          window.location.href = cfg.onSuccess.redirectUrl;
+        } else {
+          setStatus(cfg, cfg.onSuccess.message, false, responseData);
+        }
+
+      } catch (err) {
+        console.error("[fse/form] Submit error:", err);
+        setButtonState(submitBtn, "idle", cfg);
+        setStatus(cfg, cfg.onError.message, true, null);
+      }
+    });
+  }
+
+  return {
+    mount,
+  };
+
+})();

package/src/runtime/fse.payload.js

@@ -0,0 +1,25 @@
+// fse.payload.js
+// Assembles the payload envelope { version, id, submitted_at, data }.
+// No DOM access. No crypto. Depends on: FSE (global).
+
+var FSEPayload = (function () {
+
+  function build(data) {
+    if (typeof FSE === "undefined") {
+      throw new Error("[fse/payload] FSE is not defined.");
+    }
+
+    return {
+      version:      "fse.v1.0",
+      origin:       FSE.origin || "contact-form",
+      id:           crypto.randomUUID(),
+      submitted_at: new Date().toISOString(),
+      data:         data,
+    };
+  }
+
+  return {
+    build,
+  };
+
+})();