formseal-fetch 2.0.0__tar.gz

formseal_fetch-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grayguava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

formseal_fetch-2.0.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: formseal-fetch
+Version: 2.0.0
+Summary: CLI tool for fetching encrypted form submissions
+License: MIT License
+        
+        Copyright (c) 2026 grayguava
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: keyring>=25.0
+Dynamic: license-file
+
+# formseal-fetch
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.8+-3776ab?style=flat&labelColor=1e293b">
+  <img src="https://img.shields.io/badge/license-MIT-fc8181?style=flat&labelColor=1e293b">
+  <img src="https://img.shields.io/badge/formseal-ecosystem-10b981?style=flat&labelColor=1e293b">
+</p>
+
+Download encrypted form submissions from your storage backend for offline decryption.
+
+## What it does
+
+```
+Browser (formseal-embed)
+       │
+       ▼ (encrypted submissions)
+  Storage (Cloudflare KV / Supabase / ...)
+       │
+       ▼ (fsf fetch)
+  Your PC ──► ciphertexts.jsonl
+       │
+       ▼ (decrypt offline)
+  Plaintext form data
+```
+
+## Install
+
+```bash
+pip install formseal-fetch
+```
+
+## Quick start
+
+```bash
+fsf connect provider:<name>
+fsf fetch
+fsf status
+```
+
+## Features
+
+- **Secure storage** : Credentials stored in OS keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service)
+- **Deduplication** : Skips already-downloaded ciphertexts automatically
+- **Offline-capable** ; Decrypt downloaded data anytime without network access
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `fsf connect` | Connect to a storage provider |
+| `fsf fetch` | Download ciphertexts |
+| `fsf status` | Show connection info |
+| `fsf disconnect` | Clear all credentials |
+
+Run `fsf --help` for all commands.
+
+## Security
+
+Your API tokens never leave your machine.formseal-fetch:
+- Stores credentials in your OS keychain (encrypted at rest)
+- Makes direct API calls to your storage backend only
+- Sends no telemetry, has no analytics
+
+## Documentation
+
+Detailed guides: [docs/](./docs/)
+
+- [Getting Started](./docs/getting-started.md)
+- [Security](./docs/security.md)
+- [Commands Reference](./docs/reference/commands.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+
+## License
+
+MIT

formseal_fetch-2.0.0/README.md

@@ -0,0 +1,75 @@
+# formseal-fetch
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.8+-3776ab?style=flat&labelColor=1e293b">
+  <img src="https://img.shields.io/badge/license-MIT-fc8181?style=flat&labelColor=1e293b">
+  <img src="https://img.shields.io/badge/formseal-ecosystem-10b981?style=flat&labelColor=1e293b">
+</p>
+
+Download encrypted form submissions from your storage backend for offline decryption.
+
+## What it does
+
+```
+Browser (formseal-embed)
+       │
+       ▼ (encrypted submissions)
+  Storage (Cloudflare KV / Supabase / ...)
+       │
+       ▼ (fsf fetch)
+  Your PC ──► ciphertexts.jsonl
+       │
+       ▼ (decrypt offline)
+  Plaintext form data
+```
+
+## Install
+
+```bash
+pip install formseal-fetch
+```
+
+## Quick start
+
+```bash
+fsf connect provider:<name>
+fsf fetch
+fsf status
+```
+
+## Features
+
+- **Secure storage** : Credentials stored in OS keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service)
+- **Deduplication** : Skips already-downloaded ciphertexts automatically
+- **Offline-capable** ; Decrypt downloaded data anytime without network access
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `fsf connect` | Connect to a storage provider |
+| `fsf fetch` | Download ciphertexts |
+| `fsf status` | Show connection info |
+| `fsf disconnect` | Clear all credentials |
+
+Run `fsf --help` for all commands.
+
+## Security
+
+Your API tokens never leave your machine.formseal-fetch:
+- Stores credentials in your OS keychain (encrypted at rest)
+- Makes direct API calls to your storage backend only
+- Sends no telemetry, has no analytics
+
+## Documentation
+
+Detailed guides: [docs/](./docs/)
+
+- [Getting Started](./docs/getting-started.md)
+- [Security](./docs/security.md)
+- [Commands Reference](./docs/reference/commands.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+
+## License
+
+MIT

formseal_fetch-2.0.0/cli/commands/config.py

@@ -0,0 +1,194 @@
+# Config management
+
+import json
+import sys
+from pathlib import Path
+
+from cli.ui import br, fail, ok, info, warn, G, W, D, C, Y, R
+from cli.security import tokens
+
+
+def _load_version():
+    p = Path(__file__).parent.parent.parent / "version.txt"
+    if p.exists():
+        return p.read_text().strip()
+    return "dev"
+
+
+VERSION = _load_version()
+
+
+CONFIG_DIR = Path.home() / ".config" / "formseal-fetch"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+VALID_PROVIDERS = {
+    "cloudflare": {},
+}
+
+VALID_GLOBAL = {
+    "output_folder": "Output folder path",
+}
+
+
+def load_config():
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    if CONFIG_FILE.exists():
+        return json.loads(CONFIG_FILE.read_text())
+    return {}
+
+
+def save_config(cfg):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(cfg, indent=2))
+
+
+def get_token(provider: str):
+    return tokens.load_token(provider)
+
+
+def get_namespace(provider: str):
+    return tokens.load_namespace(provider)
+
+
+def run_set(args):
+    if len(args) < 2:
+        fail("Usage: fsf set <key> <value>")
+
+    key = args[0]
+    value = " ".join(args[1:])
+
+    cfg = load_config()
+
+    if key == "provider":
+        if value not in VALID_PROVIDERS:
+            fail(f"Unknown provider: {value}\nValid: {', '.join(VALID_PROVIDERS.keys())}")
+        cfg["provider"] = value
+        save_config(cfg)
+        br()
+        ok(f"Provider set to {value}")
+        br()
+        return
+
+    if key in VALID_GLOBAL:
+        cfg[key] = value
+        save_config(cfg)
+        br()
+        ok(f"Set {key} = {value}")
+        br()
+        return
+
+    fail(f"Unknown key: {key}")
+
+
+def run_status():
+    cfg = load_config()
+
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-fetch{R}  {Y}v{VERSION}{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+
+    print(f"  {D}Configuration Status:{R}")
+    br()
+
+    provider = cfg.get("provider")
+    if not provider:
+        warn("No provider configured. Run: fsf connect provider:<name>")
+        br()
+        return
+
+    def row(label, value, color=W):
+        print(f"  {D}{label:<26}{R}{color}{value}{R}")
+
+    row("Provider:", "Cloudflare")
+
+    if provider == "cloudflare":
+        namespace = get_namespace(provider)
+        token = get_token(provider)
+
+        row("KV Namespace ID:", namespace or "(not set)", W if namespace else D)
+        if namespace:
+            row("NS-ID Location:", tokens.namespace_location(provider), G)
+
+        if token:
+            try:
+                from cli.providers.cloudflare.account import get_account_id
+                account_id = get_account_id(token)
+                partial = account_id[:12] + "..." if len(account_id) > 12 else account_id
+                row("Account ID:", partial, G)
+            except Exception:
+                row("Account ID:", "(auth error)", R)
+            row("API Token:", "****")
+            row("Token Location:", tokens.token_location(provider), G)
+        else:
+            row("API Token:", "(not set)", D)
+            row("Token Location:", "Not set", D)
+
+        br()
+        row("Server Storage Type:", "Key-Value")
+
+    else:
+        fail(f"Unknown provider: {provider}")
+
+    output_folder = cfg.get("output_folder")
+    row("Output Folder:", output_folder or "(not set)", W if output_folder else D)
+
+    br()
+
+    br()
+
+
+def run_config_show():
+    cfg = load_config()
+
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-fetch{R}  {G}config{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+
+    provider = cfg.get("provider")
+
+    if not cfg:
+        info("No config. Run: fsf connect provider:<name>")
+    else:
+        for k, v in cfg.items():
+            print(f"  {D}{k}:{R}  {W}{v}{R}")
+
+    if provider:
+        token = get_token(provider)
+        print(f"  {D}token:{R}  {'****' if token else 'not set'}")
+
+    br()
+
+
+def run_disconnect():
+    br()
+    print(f"  {Y}This will delete all config and credentials.{R}")
+    print(f"  Downloaded ciphertexts will NOT be affected.")
+    br()
+    sys.stdout.write(f"  Continue? [y/N]: ")
+    sys.stdout.flush()
+    confirm = input().strip().lower()
+    
+    if confirm != "y":
+        br()
+        info("Cancelled.")
+        br()
+        return
+    
+    cfg = load_config()
+    provider = cfg.get("provider")
+    
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()
+    
+    if provider:
+        tokens.clear_all(provider)
+    
+    br()
+    ok("Disconnected. All config and credentials cleared.")
+    br()
+
+
+run_logout = run_disconnect

formseal_fetch-2.0.0/cli/commands/fetch.py

@@ -0,0 +1,72 @@
+# Fetch ciphertexts
+
+import argparse
+
+from cli.ui import br, fail, ok, info, G, W, D, C, R
+from cli.commands.config import load_config
+from cli.security import tokens
+
+
+def run(args):
+    parser = argparse.ArgumentParser(prog="fsf fetch")
+    parser.add_argument("--output", default=None)
+    parsed = parser.parse_args(args)
+
+    cfg = load_config()
+    provider = cfg.get("provider")
+    output_folder = cfg.get("output_folder", "data")
+
+    if not provider:
+        fail("No provider set. Run: fsf connect provider:<name>")
+
+    if parsed.output:
+        output_path = parsed.output
+    else:
+        output_path = f"{output_folder}/ciphertexts.jsonl"
+
+    token = tokens.load_token(provider)
+    if not token:
+        fail("No token. Run: fsf connect provider:<name> to set token")
+
+    if provider == "cloudflare":
+        namespace = tokens.load_namespace(provider)
+        if not namespace:
+            fail("No namespace. Run: fsf connect provider:<name> to set namespace")
+
+        try:
+            from cli.providers.cloudflare.account import get_account_id
+            account_id = get_account_id(token)
+        except Exception as e:
+            fail(f"Auth failed: {e}")
+
+        br()
+        provider_display = f"{provider.capitalize()} KV"
+        print(f"{C} \u250c\u2500 {R}{W}formseal-fetch{R}  {G}{provider_display}{R}")
+        print(G + " " + "\u2500" * 52 + R)
+        br()
+
+        account_trunc = account_id[:8] + "***" if len(account_id) > 8 else account_id
+        namespace_trunc = namespace[:8] + "***" if len(namespace) > 8 else namespace
+
+        print(f"{D}>> Account:{R}  {D}{account_trunc}{R}")
+        print(f"{D}>> Namespace:{R} {D}{namespace_trunc}{R}")
+        br()
+
+        try:
+            from cli.providers.cloudflare.storage import fetch as storage_fetch
+            written, skipped = storage_fetch(
+                namespace=namespace,
+                account_id=account_id,
+                token=token,
+                output_path=output_path,
+            )
+        except Exception as e:
+            fail(f"Fetch failed: {e}")
+
+        br()
+        ok(f"{written} new ciphertexts saved → {output_path}")
+        if skipped:
+            print(f"  {D}({skipped} duplicates skipped){R}")
+        br()
+    else:
+        fail(f"Unknown provider: {provider}")

formseal_fetch-2.0.0/cli/commands/providers.py

@@ -0,0 +1,39 @@
+# List providers
+
+from pathlib import Path
+
+from cli.ui import br, C, G, Y, W, D, R
+
+
+def _load_version():
+    p = Path(__file__).parent.parent.parent / "version.txt"
+    if p.exists():
+        return p.read_text().strip()
+    return "dev"
+
+
+VERSION = _load_version()
+
+
+def run(args):
+    _list_providers()
+
+
+def _list_providers():
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-fetch{R}  {Y}v{VERSION}{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+
+    print(f"  {G}Available providers:{R}")
+    br()
+    print(f"    {W}> Cloudflare{R}   -  Cloudflare KV")
+    br()
+    print(f"    {W}> Supabase{R}     -  PostgreSQL DB (coming soon)")
+    br()
+
+
+def _help():
+    return [
+        ("fsf providers", "list available providers"),
+    ]

formseal_fetch-2.0.0/cli/commands/setup.py

@@ -0,0 +1,127 @@
+# Connect commands
+
+import sys
+import json
+from pathlib import Path
+
+from cli.ui import br, fail, ok, info, warn, G, W, D, C, Y, O, R
+from cli.commands.config import load_config, save_config
+from cli.security import tokens
+
+
+SETUP_SCHEMA = {
+    "cloudflare": {
+        "kv": {
+            "config_fields": [
+                {"key": "namespace", "prompt": "KV Namespace ID", "required": True},
+            ],
+        }
+    }
+}
+
+
+def _parse_args(args):
+    parsed = {}
+    for arg in args:
+        if ":" not in arg:
+            fail(f"Invalid format: {arg}\n           Use flag:value (e.g., provider:<name>)")
+        key, value = arg.split(":", 1)
+        parsed[key] = value
+    return parsed
+
+
+def run(args):
+    if not args:
+        fail("Usage: fsf connect provider:<name> [namespace:<id>] [output:<path>]")
+
+    parsed = _parse_args(args)
+
+    if "provider" not in parsed:
+        fail("provider is required.\n           Usage: fsf connect provider:<name> [...]")
+
+    provider = parsed["provider"].lower()
+    if provider not in SETUP_SCHEMA:
+        fail(f"Unknown provider: {provider}\n           Run fsf providers to see available.")
+
+    _setup_flow(provider, parsed)
+
+
+def _setup_flow(provider, parsed):
+    print()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-fetch{R}  {G}setup{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    print()
+
+    cfg = load_config()
+    cfg["provider"] = provider
+
+    # Get config fields from schema
+    fields = SETUP_SCHEMA[provider]["kv"]["config_fields"]
+
+    # Ask for namespace if not provided
+    namespace = parsed.get("namespace")
+    if not namespace:
+        for field in fields:
+            prompt = field["prompt"]
+            try:
+                sys.stdout.write(f"  {prompt}: ")
+                sys.stdout.flush()
+                namespace = input().strip()
+            except KeyboardInterrupt:
+                br()
+                info("Cancelled.")
+                br()
+                return
+            if field.get("required") and not namespace:
+                fail(f"{prompt} is required")
+            break
+
+    if namespace:
+        tokens.save_namespace(provider, namespace)
+
+    # Ask for token
+    if "token" in parsed:
+        token = parsed["token"]
+    else:
+        try:
+            sys.stdout.write("  Account API Token: ")
+            sys.stdout.flush()
+            token = sys.stdin.readline().strip()
+        except KeyboardInterrupt:
+            br()
+            info("Cancelled.")
+            br()
+            return
+        if not token:
+            fail("Account API Token is required")
+
+    token = "".join(c for c in token if c.isprintable()).strip()
+    if not token:
+        fail("Account API Token is required")
+
+    tokens.save_token(provider, token)
+
+    # Ask for output folder
+    if "output" in parsed:
+        output_folder = parsed["output"]
+    else:
+        try:
+            sys.stdout.write(f"  Output Folder [{D}data{R}]: ")
+            sys.stdout.flush()
+            output_folder = input().strip()
+            if not output_folder:
+                output_folder = "data"
+        except KeyboardInterrupt:
+            br()
+            info("Cancelled.")
+            br()
+            return
+    cfg["output_folder"] = output_folder
+    print()
+
+    save_config(cfg)
+
+    print(f"{G} \u2713{R} Saved!")
+    print()
+    print(f"  Run {W}fsf fetch{R} to download ciphertexts")
+    print()

formseal_fetch-2.0.0/cli/fsf.py

@@ -0,0 +1,124 @@
+# Main entry point
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from cli.ui import br, fail, info, warn, C, G, W, Y, R, D, GRAY
+from cli.commands.config import run_status, run_set, run_disconnect
+from cli.commands.setup import run as run_connect
+from cli.commands.fetch import run as run_fetch
+from cli.commands.providers import run as run_providers
+
+
+def _load_version():
+    p = Path(__file__).parent.parent / "version.txt"
+    if p.exists():
+        return p.read_text().strip()
+    return "dev"
+
+
+VERSION = _load_version()
+
+
+COMMANDS = {
+    "connect": ("Connect to a provider", lambda a: run_connect(a)),
+    "fetch": ("Fetch ciphertexts", lambda a: run_fetch(a)),
+    "status": ("Show connection status", lambda a: run_status()),
+    "set": ("Set a config value", run_set),
+    "disconnect": ("Clear all credentials", lambda a: run_disconnect()),
+    "providers": ("List available providers", lambda a: run_providers(a)),
+}
+
+
+HELP_GROUPS = {
+    "Connect": [
+        ("fsf connect provider:<name>", "connect to a storage provider"),
+        ("fsf disconnect", "clear configuration"),
+    ],
+    "Fetch": [
+        ("fsf fetch", "download ciphertexts"),
+        ("fsf fetch --output <file>", "custom output path"),
+    ],
+    "Config": [
+        ("fsf status", "show configuration"),
+        ("fsf set <key> <value>", "set config value"),
+    ],
+    "Info": [
+        ("fsf providers", "list available providers"),
+        ("fsf --about", "show project info"),
+    ],
+    "Docs": [
+        ("https://github.com/formseal/formseal-fetch", None),
+    ],
+}
+
+
+def _show_help():
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-fetch{R}  {Y}v{VERSION}{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+
+    for group, cmds in HELP_GROUPS.items():
+        print(f"  {GRAY}>> {group}{R}")
+        print(G + " " + "\u2500" * 52 + R)
+        for cmd, desc in cmds:
+            if desc:
+                print(f"  {W}{cmd:<35}{R}  {G}{desc}{R}")
+            else:
+                print(f"  {C}{cmd}{R}")
+        br()
+
+
+def _show_about():
+    br()
+    print(f"{C} \u250c\u2500 {R}{W}formseal-fetch{R}  {Y}v{VERSION}{R}")
+    print(G + " " + "\u2500" * 52 + R)
+    br()
+    print(f"  {W}formseal-fetch{R} - CLI for fetching encrypted form submissions")
+    br()
+    print(f"  {G}Repository:{R}  https://github.com/formseal/formseal-fetch")
+    br()
+
+
+def main():
+    if len(sys.argv) < 2:
+        _show_help()
+        return
+
+    cmd = sys.argv[1].lower()
+    args = sys.argv[2:]
+
+    if cmd == "-h" or cmd == "--help":
+        _show_help()
+        return
+
+    if cmd == "--about":
+        _show_about()
+        return
+
+    if cmd not in COMMANDS:
+        br()
+        fail(f"Unknown command: {cmd}\nRun 'fsf --help' for available commands")
+
+    _, handler = COMMANDS[cmd]
+
+    if handler is None:
+        br()
+        fail(f"Command not implemented: {cmd}")
+
+    try:
+        handler(args)
+    except KeyboardInterrupt:
+        br()
+        info("Interrupted.")
+        br()
+        sys.exit(130)
+    except Exception as e:
+        fail(str(e))
+
+
+if __name__ == "__main__":
+    main()

formseal_fetch-2.0.0/cli/providers/cloudflare/account.py

@@ -0,0 +1,69 @@
+# Cloudflare account authentication
+
+import json
+import urllib.request
+import urllib.error
+
+from cli.ui import fail
+
+
+class AuthError(Exception):
+    """Raised when Cloudflare authentication fails."""
+    pass
+
+
+class TokenError(Exception):
+    """Raised when token is invalid or missing."""
+    pass
+
+
+def get_account_id(token):
+    """Fetch account_id from Cloudflare API."""
+    if not token:
+        raise TokenError("Token is empty")
+    
+    token = token.strip()
+    if not token:
+        raise TokenError("Token is blank after stripping whitespace")
+    
+    req = urllib.request.Request(
+        "https://api.cloudflare.com/client/v4/accounts",
+        headers={"Authorization": f"Bearer {token}"}
+    )
+    
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        raise AuthError(f"HTTP {e.code}: {body}")
+    except json.JSONDecodeError as e:
+        raise AuthError(f"Invalid API response: {e}")
+    except urllib.error.URLError as e:
+        raise AuthError(f"Network error: {e.reason}")
+    
+    if not data.get("success"):
+        errors = data.get("errors", [])
+        if errors:
+            msg = errors[0].get("message", "Unknown error")
+            if "token" in msg.lower():
+                raise TokenError(f"Invalid token: {msg}")
+            raise AuthError(msg)
+        raise AuthError("Unknown API error")
+    
+    accounts = data.get("result", [])
+    if not accounts:
+        raise AuthError("No accounts found. Token needs 'Account Settings: Read' scope.")
+    
+    return accounts[0]["id"]
+
+
+def validate_token(token):
+    """Check if token is valid. Returns True/False, never raises."""
+    try:
+        get_account_id(token)
+        return True
+    except (TokenError, AuthError) as e:
+        return False
+    except Exception:
+        return False

formseal_fetch-2.0.0/cli/providers/cloudflare/storage/__init__.py

@@ -0,0 +1,3 @@
+from cli.providers.cloudflare.storage.kv import fetch
+
+__all__ = ["fetch"]

formseal_fetch-2.0.0/cli/providers/cloudflare/storage/kv.py

@@ -0,0 +1,80 @@
+# Cloudflare KV storage
+
+import json
+import urllib.request
+import urllib.error
+import urllib.parse
+from pathlib import Path
+
+from cli.ui import fail, info
+
+
+def _get(url, token):
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        fail(f"HTTP {e.code}: {e.read().decode()}")
+
+
+def _get_raw(url, token):
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return resp.read().decode("utf-8").strip()
+    except urllib.error.HTTPError as e:
+        fail(f"HTTP {e.code}: {e.read().decode()}")
+
+
+def _load_seen(output_path) -> set:
+    p = Path(output_path)
+    if not p.exists():
+        return set()
+    return {line.strip() for line in p.read_text(encoding="utf-8").splitlines() if line.strip()}
+
+
+def fetch(namespace, account_id, token, output_path):
+    """Fetch all values from a KV namespace."""
+    base = f"https://api.cloudflare.com/client/v4/accounts/{account_id}/storage/kv/namespaces/{namespace}"
+
+    # List all keys (paginated)
+    all_keys = []
+    cursor = None
+
+    while True:
+        url = f"{base}/keys" + (f"?cursor={cursor}" if cursor else "")
+        data = _get(url, token)
+        if not data.get("success"):
+            fail(f"API error: {data.get('errors')}")
+        all_keys.extend(k["name"] for k in data.get("result", []))
+        cursor = data.get("result_info", {}).get("cursor")
+        if not cursor:
+            break
+
+    info(f"Found {len(all_keys)} entries")
+
+    if not all_keys:
+        info("No data to fetch.")
+        return 0, 0
+
+    # Deduplicate against existing
+    seen = _load_seen(output_path)
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+
+    written = 0
+    skipped = 0
+
+    with open(output_path, "a", encoding="utf-8") as f:
+        for key in all_keys:
+            value = _get_raw(f"{base}/values/{urllib.parse.quote(key, safe='')}", token)
+            if not value:
+                continue
+            if value in seen:
+                skipped += 1
+                continue
+            f.write(value + "\n")
+            seen.add(value)
+            written += 1
+
+    return written, skipped

formseal_fetch-2.0.0/cli/security/tokens.py

@@ -0,0 +1,166 @@
+# Credential storage (keyring + JSON fallback)
+
+import json
+import base64
+from pathlib import Path
+
+try:
+    import keyring
+    HAS_KEYRING = True
+except ImportError:
+    HAS_KEYRING = False
+
+SERVICE = "formseal-fetch"
+
+CONFIG_DIR = Path.home() / ".config" / "formseal-fetch"
+SECRETS_FILE = CONFIG_DIR / "secrets.json"
+
+
+def _ensure_config_dir():
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _load_secrets() -> dict:
+    if not SECRETS_FILE.exists():
+        return {}
+    try:
+        return json.loads(SECRETS_FILE.read_text())
+    except:
+        return {}
+
+
+def _save_secrets(secrets: dict):
+    _ensure_config_dir()
+    SECRETS_FILE.write_text(json.dumps(secrets, indent=2))
+
+
+def save_token(provider: str, token: str) -> bool:
+    """Save API token to OS keyring. Falls back to JSON if keyring fails."""
+    if HAS_KEYRING:
+        try:
+            keyring.set_password(SERVICE, f"{provider}:api-token", token)
+            return True
+        except Exception:
+            pass
+    
+    # Fallback to JSON file
+    secrets = _load_secrets()
+    secrets[f"{provider}:token"] = base64.b64encode(token.encode()).decode()
+    _save_secrets(secrets)
+    return True
+
+
+def load_token(provider: str) -> str | None:
+    """Load API token from OS keyring. Falls back to JSON if not in keyring."""
+    if HAS_KEYRING:
+        try:
+            token = keyring.get_password(SERVICE, f"{provider}:api-token")
+            if token:
+                return token
+        except Exception:
+            pass
+    
+    # Fallback to JSON file
+    secrets = _load_secrets()
+    encoded = secrets.get(f"{provider}:token")
+    if encoded:
+        return base64.b64decode(encoded.encode()).decode().strip()
+    return None
+
+
+def delete_token(provider: str):
+    """Delete API token from keyring. Falls back to JSON if keyring fails."""
+    if HAS_KEYRING:
+        try:
+            keyring.delete_password(SERVICE, f"{provider}:api-token")
+            return
+        except Exception:
+            pass
+    
+    secrets = _load_secrets()
+    secrets.pop(f"{provider}:token", None)
+    _save_secrets(secrets)
+
+
+def save_namespace(provider: str, namespace: str) -> bool:
+    """Save KV namespace ID to OS keyring. Falls back to JSON."""
+    if HAS_KEYRING:
+        try:
+            keyring.set_password(SERVICE, f"{provider}:kv-namespace", namespace)
+            return True
+        except Exception:
+            pass
+    
+    # Fallback to JSON file
+    secrets = _load_secrets()
+    secrets[f"{provider}:namespace"] = base64.b64encode(namespace.encode()).decode()
+    _save_secrets(secrets)
+    return True
+
+
+def load_namespace(provider: str) -> str | None:
+    """Load KV namespace ID from OS keyring. Falls back to JSON."""
+    if HAS_KEYRING:
+        try:
+            namespace = keyring.get_password(SERVICE, f"{provider}:kv-namespace")
+            if namespace:
+                return namespace
+        except Exception:
+            pass
+    
+    # Fallback to JSON file
+    secrets = _load_secrets()
+    encoded = secrets.get(f"{provider}:namespace")
+    if encoded:
+        return base64.b64decode(encoded.encode()).decode().strip()
+    return None
+
+
+def delete_namespace(provider: str):
+    """Delete namespace from keyring. Falls back to JSON if keyring fails."""
+    if HAS_KEYRING:
+        try:
+            keyring.delete_password(SERVICE, f"{provider}:kv-namespace")
+            return
+        except Exception:
+            pass
+    
+    secrets = _load_secrets()
+    secrets.pop(f"{provider}:namespace", None)
+    _save_secrets(secrets)
+
+
+def token_location(provider: str) -> str:
+    """Check where token is stored."""
+    if HAS_KEYRING:
+        try:
+            if keyring.get_password(SERVICE, f"{provider}:api-token"):
+                return "OS Keychain"
+        except Exception:
+            pass
+    
+    secrets = _load_secrets()
+    if f"{provider}:token" in secrets:
+        return "Config File"
+    return "Not set"
+
+
+def namespace_location(provider: str) -> str:
+    """Check where namespace is stored."""
+    if HAS_KEYRING:
+        try:
+            if keyring.get_password(SERVICE, f"{provider}:kv-namespace"):
+                return "OS Keychain"
+        except Exception:
+            pass
+    
+    secrets = _load_secrets()
+    if f"{provider}:namespace" in secrets:
+        return "Config File"
+    return "Not set"
+
+
+def clear_all(provider: str):
+    """Clear all secrets for a provider."""
+    delete_token(provider)
+    delete_namespace(provider)

formseal_fetch-2.0.0/cli/ui.py

@@ -0,0 +1,89 @@
+# Terminal output primitives
+
+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
+
+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"
+
+O = "\x1b[38;5;208m"   
+S = "\x1b[38;5;112m"  
+G = "\x1b[38;5;244m"  
+C = "\x1b[38;5;117m"  
+Y = "\x1b[38;5;103m" 
+W = WHITE + BOLD
+D = DIM
+R = RESET
+
+
+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   = 12
+    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"  {O}{msg}{R}")
+
+
+def link(msg):
+    print(f"  {O}{msg}{R}")
+
+
+def ok(msg):
+    print(f"  {G}\u2713{R} {msg}")
+
+
+def info(msg):
+    print(f"  {O}{msg}{R}")
+
+
+def warn(msg):
+    print(f"  {Y}Warning:{R} {msg}")

formseal_fetch-2.0.0/formseal_fetch.egg-info/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: formseal-fetch
+Version: 2.0.0
+Summary: CLI tool for fetching encrypted form submissions
+License: MIT License
+        
+        Copyright (c) 2026 grayguava
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: keyring>=25.0
+Dynamic: license-file
+
+# formseal-fetch
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.8+-3776ab?style=flat&labelColor=1e293b">
+  <img src="https://img.shields.io/badge/license-MIT-fc8181?style=flat&labelColor=1e293b">
+  <img src="https://img.shields.io/badge/formseal-ecosystem-10b981?style=flat&labelColor=1e293b">
+</p>
+
+Download encrypted form submissions from your storage backend for offline decryption.
+
+## What it does
+
+```
+Browser (formseal-embed)
+       │
+       ▼ (encrypted submissions)
+  Storage (Cloudflare KV / Supabase / ...)
+       │
+       ▼ (fsf fetch)
+  Your PC ──► ciphertexts.jsonl
+       │
+       ▼ (decrypt offline)
+  Plaintext form data
+```
+
+## Install
+
+```bash
+pip install formseal-fetch
+```
+
+## Quick start
+
+```bash
+fsf connect provider:<name>
+fsf fetch
+fsf status
+```
+
+## Features
+
+- **Secure storage** : Credentials stored in OS keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service)
+- **Deduplication** : Skips already-downloaded ciphertexts automatically
+- **Offline-capable** ; Decrypt downloaded data anytime without network access
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `fsf connect` | Connect to a storage provider |
+| `fsf fetch` | Download ciphertexts |
+| `fsf status` | Show connection info |
+| `fsf disconnect` | Clear all credentials |
+
+Run `fsf --help` for all commands.
+
+## Security
+
+Your API tokens never leave your machine.formseal-fetch:
+- Stores credentials in your OS keychain (encrypted at rest)
+- Makes direct API calls to your storage backend only
+- Sends no telemetry, has no analytics
+
+## Documentation
+
+Detailed guides: [docs/](./docs/)
+
+- [Getting Started](./docs/getting-started.md)
+- [Security](./docs/security.md)
+- [Commands Reference](./docs/reference/commands.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+
+## License
+
+MIT

formseal_fetch-2.0.0/formseal_fetch.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+cli/fsf.py
+cli/ui.py
+cli/commands/__init__.py
+cli/commands/config.py
+cli/commands/fetch.py
+cli/commands/providers.py
+cli/commands/setup.py
+cli/providers/__init__.py
+cli/providers/cloudflare/account.py
+cli/providers/cloudflare/storage/__init__.py
+cli/providers/cloudflare/storage/kv.py
+cli/security/tokens.py
+formseal_fetch.egg-info/PKG-INFO
+formseal_fetch.egg-info/SOURCES.txt
+formseal_fetch.egg-info/dependency_links.txt
+formseal_fetch.egg-info/entry_points.txt
+formseal_fetch.egg-info/requires.txt
+formseal_fetch.egg-info/top_level.txt

formseal_fetch-2.0.0/formseal_fetch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

formseal_fetch-2.0.0/formseal_fetch.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fsf = cli.fsf:main

formseal_fetch-2.0.0/formseal_fetch.egg-info/requires.txt

@@ -0,0 +1 @@
+keyring>=25.0

formseal_fetch-2.0.0/formseal_fetch.egg-info/top_level.txt

@@ -0,0 +1 @@
+cli

formseal_fetch-2.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=65.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "formseal-fetch"
+version = "2.0.0"
+description = "CLI tool for fetching encrypted form submissions"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+dependencies = [
+    "keyring>=25.0",
+]
+
+[project.scripts]
+fsf = "cli.fsf:main"
+
+[tool.setuptools]
+packages = ["cli", "cli.commands", "cli.providers", "cli.providers.cloudflare", "cli.providers.cloudflare.storage", "cli.security"]

formseal_fetch-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+