@ao_zorin/zocket 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zocket contributors
+
+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.

package/README.md

@@ -0,0 +1,92 @@
+# zocket
+
+Local encrypted vault + web panel + MCP server for AI agent workflows.
+
+## What zocket provides
+
+- encrypted secret vault across projects/sessions
+- local web panel (`127.0.0.1:18001`)
+- MCP server:
+  - stdio
+  - SSE (`127.0.0.1:18002/sse`) for Claude Code
+  - streamable HTTP (`127.0.0.1:18003/mcp`) for Codex
+- EN/RU UI and CLI
+- first-run web setup:
+  - set your own password
+  - generate strong password
+  - continue without password (with explicit warning)
+- project-to-folder mapping with folder picker
+- audit log, backup/restore, key rotation
+- Linux hardened system services (`zocketd`)
+
+## Install (instant)
+
+```bash
+npm i -g @zocket/cli
+zocket setup
+```
+
+## Install (dev)
+
+### Python
+```bash
+pip install -e .
+```
+
+### npm wrapper
+```bash
+npm install
+npm run smoke:npm
+```
+
+or global from git:
+```bash
+npm i -g github:your-org/zocket
+zocket setup
+```
+
+## Quick start
+
+```bash
+zocket init
+zocket web --host 127.0.0.1 --port 18001
+zocket mcp --transport sse --mode metadata --host 127.0.0.1 --port 18002
+zocket mcp --transport streamable-http --mode metadata --host 127.0.0.1 --port 18003
+```
+
+Open `http://127.0.0.1:18001`.
+
+## Docs
+
+- installation (Windows/Linux/macOS): [`docs/INSTALL.md`](docs/INSTALL.md)
+- MCP clients (Codex/Claude Code): [`docs/CLIENTS_MCP.md`](docs/CLIENTS_MCP.md)
+- local models (Ollama/Hugging Face): [`docs/LOCAL_MODELS.md`](docs/LOCAL_MODELS.md)
+- AI one-file auto-deploy playbook: [`docs/AI_AUTODEPLOY.md`](docs/AI_AUTODEPLOY.md)
+- git + npm + pypi release flow: [`docs/GIT_NPM_RELEASE.md`](docs/GIT_NPM_RELEASE.md)
+- external source links: [`docs/SOURCES.md`](docs/SOURCES.md)
+
+## Security defaults
+
+- keep MCP in `metadata` mode unless admin tools are required
+- bind web/MCP to loopback
+- on Linux production use:
+  ```bash
+  sudo env ZOCKET_HOME=/var/lib/zocket zocket harden install-linux-system \
+    --service-user zocketd \
+    --zocket-home /var/lib/zocket \
+    --web-port 18001 \
+    --mcp-host 127.0.0.1 \
+    --mcp-port 18002 \
+    --mcp-mode metadata
+  ```
+
+## Development
+
+```bash
+PYTHONPATH=. pytest -q
+bash scripts/release-check.sh
+```
+
+## License
+
+MIT, see [`LICENSE`](LICENSE).

package/bin/zocket-setup.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const cp = require("child_process");
+const path = require("path");
+
+const launcher = path.resolve(__dirname, "zocket.cjs");
+const res = cp.spawnSync(process.execPath, [launcher, "setup"], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+process.exit(res.status === null ? 1 : res.status);

package/bin/zocket.cjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+const cp = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const isWin = process.platform === "win32";
+const args = process.argv.slice(2);
+const pkgRoot = path.resolve(__dirname, "..");
+const launcherVersion = "1.0.0";
+
+function fail(msg, code = 1) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(code);
+}
+
+function run(cmd, cmdArgs, opts = {}) {
+  const res = cp.spawnSync(cmd, cmdArgs, {
+    stdio: "inherit",
+    env: process.env,
+    ...opts,
+  });
+  return res.status === null ? 1 : res.status;
+}
+
+function probe(cmd, cmdArgs) {
+  const res = cp.spawnSync(cmd, cmdArgs, {
+    stdio: "ignore",
+    env: process.env,
+  });
+  return res.status === 0;
+}
+
+function findPython() {
+  const candidates = isWin
+    ? [
+        { cmd: "py", prefix: ["-3"] },
+        { cmd: "python", prefix: [] },
+        { cmd: "python3", prefix: [] },
+      ]
+    : [
+        { cmd: "python3", prefix: [] },
+        { cmd: "python", prefix: [] },
+      ];
+
+  for (const item of candidates) {
+    const ok = probe(item.cmd, [...item.prefix, "-c", "import sys;sys.exit(0)"]);
+    if (ok) {
+      return item;
+    }
+  }
+  return null;
+}
+
+function installRoot() {
+  if (isWin) {
+    const base = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    return path.join(base, "zocket");
+  }
+  return path.join(os.homedir(), ".local", "share", "zocket");
+}
+
+function venvPython(venvDir) {
+  return isWin
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python3");
+}
+
+function removeIfExists(target) {
+  if (fs.existsSync(target)) {
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+}
+
+function prepareInstallSource(rootDir) {
+  const sourceDir = path.join(rootDir, "npm-install-source");
+  removeIfExists(sourceDir);
+  fs.mkdirSync(sourceDir, { recursive: true });
+
+  const filesToCopy = ["pyproject.toml", "README.md", "zocket"];
+  for (const item of filesToCopy) {
+    const src = path.join(pkgRoot, item);
+    if (!fs.existsSync(src)) {
+      continue;
+    }
+    const dst = path.join(sourceDir, item);
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+      fs.cpSync(src, dst, { recursive: true });
+    } else {
+      fs.copyFileSync(src, dst);
+    }
+  }
+  return sourceDir;
+}
+
+function ensureVenv() {
+  const root = installRoot();
+  const venvDir = path.join(root, "venv");
+  const marker = path.join(root, "npm-launcher-version.txt");
+  const pyBin = venvPython(venvDir);
+  let needInstall = !fs.existsSync(pyBin);
+
+  if (!needInstall && fs.existsSync(marker)) {
+    const current = fs.readFileSync(marker, "utf-8").trim();
+    if (current !== launcherVersion) {
+      needInstall = true;
+    }
+  }
+
+  if (!needInstall) {
+    const healthy = probe(pyBin, ["-c", "import zocket, cryptography"]);
+    if (!healthy) {
+      needInstall = true;
+    }
+  }
+
+  if (!needInstall) {
+    return pyBin;
+  }
+
+  const py = findPython();
+  if (!py) {
+    fail(
+      [
+        "Python 3.10+ was not found.",
+        "Install Python first, then rerun:",
+        "  zocket setup",
+      ].join("\n")
+    );
+  }
+
+  fs.mkdirSync(root, { recursive: true });
+  let code = run(py.cmd, [...py.prefix, "-m", "venv", venvDir]);
+  if (code !== 0) {
+    fail("Failed to create virtual environment for zocket.");
+  }
+
+  code = run(pyBin, ["-m", "pip", "install", "--upgrade", "pip", "setuptools", "wheel"]);
+  if (code !== 0) {
+    fail("Failed to bootstrap pip in zocket virtual environment.");
+  }
+
+  // Install from a writable user-owned source copy to avoid permission issues.
+  const sourceDir = prepareInstallSource(root);
+  code = run(pyBin, ["-m", "pip", "install", sourceDir]);
+  if (code !== 0) {
+    fail("Failed to install zocket Python package from npm bundle.");
+  }
+
+  fs.writeFileSync(marker, `${launcherVersion}\n`, "utf-8");
+  return pyBin;
+}
+
+if (args[0] === "setup") {
+  ensureVenv();
+  process.stdout.write("zocket runtime is installed.\n");
+  process.exit(0);
+}
+
+if (args[0] === "doctor") {
+  const py = findPython();
+  const root = installRoot();
+  const pyBin = venvPython(path.join(root, "venv"));
+  process.stdout.write(`python_found=${py ? "yes" : "no"}\n`);
+  process.stdout.write(`venv_python=${pyBin}\n`);
+  process.stdout.write(`venv_exists=${fs.existsSync(pyBin) ? "yes" : "no"}\n`);
+  process.exit(0);
+}
+
+const runtimePython = ensureVenv();
+const code = run(runtimePython, ["-m", "zocket", ...args]);
+process.exit(code);

package/docs/AI_AUTODEPLOY.md

@@ -0,0 +1,52 @@
+# AI Auto-Deploy Playbook
+
+This is the file you can send to an AI coding agent so it can deploy zocket end-to-end.
+
+## One-command bootstrap
+
+If this repo is already present locally:
+```bash
+python3 scripts/ai-autodeploy.py --repo-url https://github.com/your-org/zocket.git --repo-ref main
+```
+
+If only the file is available, the script will clone the repo and run the platform installer.
+
+## Agent task prompt (copy/paste)
+
+```text
+Deploy zocket on this machine with secure defaults:
+1) Detect OS and shell.
+2) Run scripts/ai-autodeploy.py with:
+   --lang en
+   --web-port 18001
+   --mcp-port 18002
+   --mcp-mode metadata
+   --autostart user (Linux/macOS) or enabled startup task (Windows)
+3) Verify:
+   - web panel on http://127.0.0.1:18001
+   - MCP SSE endpoint on http://127.0.0.1:18002/sse (Claude Code)
+   - MCP streamable endpoint on http://127.0.0.1:18003/mcp (Codex)
+4) Configure MCP clients using docs/CLIENTS_MCP.md (Codex + Claude Code only).
+5) Return final report with commands executed and health-check results.
+```
+
+## Optional production profile (Linux system services)
+
+```bash
+python3 scripts/ai-autodeploy.py \
+  --repo-url https://github.com/your-org/zocket.git \
+  --repo-ref main \
+  --autostart system \
+  --zocket-home /var/lib/zocket
+```
+
+## Post-deploy checklist for agent
+
+1. Confirm web login/setup page opens.
+2. Confirm MCP HTTP is reachable on loopback only.
+3. Configure one client (Codex or Claude Code) and run `list_projects` tool.
+4. Ensure no secret values are returned in metadata mode.
+5. Save final links:
+   - [INSTALL.md](/home/zorin/project/zocket/docs/INSTALL.md)
+   - [CLIENTS_MCP.md](/home/zorin/project/zocket/docs/CLIENTS_MCP.md)
+   - [LOCAL_MODELS.md](/home/zorin/project/zocket/docs/LOCAL_MODELS.md)

package/docs/CLIENTS_MCP.md

@@ -0,0 +1,59 @@
+# MCP Client Integration (Codex + Claude Code)
+
+This file contains ready-to-use zocket MCP configs for:
+- Codex CLI
+- Claude Code
+
+Use safest mode by default:
+- `metadata` (recommended)
+
+Use admin mode only when needed:
+- `admin`
+
+---
+
+## Endpoints
+
+- Claude Code (SSE):
+  - `http://127.0.0.1:18002/sse`
+
+- Codex (streamable HTTP):
+  - `http://127.0.0.1:18003/mcp`
+
+---
+
+## Claude Code
+
+Recommended: SSE (loopback only).
+
+```bash
+claude mcp add --transport sse zocket http://127.0.0.1:18002/sse
+claude mcp list
+```
+
+Note: Claude Code uses `--transport sse` (not http) for SSE endpoints.
+
+---
+
+## Codex CLI
+
+Recommended: streamable HTTP.
+
+```bash
+codex mcp add zocket --url http://127.0.0.1:18003/mcp
+codex mcp list
+```
+
+Config file alternative (`~/.codex/config.toml`):
+```toml
+[mcp_servers.zocket]
+url = "http://127.0.0.1:18003/mcp"
+```
+
+---
+
+## Security defaults
+
+- Prefer `metadata` mode in all clients.
+- Keep MCP bound to `127.0.0.1`.
+- Do not expose these ports to the network.

package/docs/INSTALL.md

@@ -0,0 +1,288 @@
+# Install Guide (Windows / Linux / macOS)
+
+This guide installs **zocket** as:
+- local web panel on `127.0.0.1:18001`
+- MCP SSE server on `127.0.0.1:18002/sse` (Claude Code)
+- MCP streamable HTTP server on `127.0.0.1:18003/mcp` (Codex)
+- optional MCP stdio server for local CLI use
+
+## 1) Quick Install (recommended)
+
+### Linux and macOS
+```bash
+curl -fsSL https://raw.githubusercontent.com/your-org/zocket/main/scripts/install-zocket.sh | bash
+```
+
+If you run from a local clone:
+```bash
+bash scripts/install-zocket.sh --source local
+```
+
+### Windows (PowerShell)
+```powershell
+irm https://raw.githubusercontent.com/your-org/zocket/main/scripts/install-zocket.ps1 | iex
+```
+
+If you run from a local clone:
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install-zocket.ps1 -Source Local
+```
+
+## 2) Linux details
+
+### Debian/Ubuntu and Debian-based
+Installer auto-installs:
+- `python3`
+- `python3-venv`
+- `python3-pip`
+- `git`
+- `curl`
+
+Equivalent manual install:
+```bash
+sudo apt-get update
+sudo apt-get install -y python3 python3-venv python3-pip git curl
+```
+
+### Other Linux distros
+Installer supports:
+- `dnf`/`yum` (RHEL/Fedora)
+- `pacman` (Arch)
+- `zypper` (openSUSE)
+- `apk` (Alpine)
+
+If your distro is unsupported, install manually:
+- Python `>=3.10`
+- `pip`
+- `venv`
+- `git`
+
+## 3) macOS details
+
+Installer uses Homebrew when dependencies are missing:
+```bash
+brew install python git curl
+```
+
+## 4) Windows details
+
+Requirements:
+- Python 3.10+ (recommended from `python.org` or `winget`)
+- Git for Windows
+
+Optional autostart:
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install-zocket.ps1 -EnableAutostart
+```
+
+This creates scheduled tasks:
+- `ZocketWeb`
+- `ZocketMcpHttp`
+
+## 5) NPM package usage
+
+This repo now includes an npm wrapper package.
+
+Global install from npm:
+```bash
+npm i -g @zocket/cli
+zocket setup
+```
+
+Or install from your git repo (example):
+```bash
+npm i -g github:your-org/zocket
+```
+
+First-run setup:
+```bash
+zocket setup
+```
+
+Then use normal CLI:
+```bash
+zocket init
+zocket web --host 127.0.0.1 --port 18001
+zocket mcp --transport sse --mode metadata --host 127.0.0.1 --port 18002
+zocket mcp --transport streamable-http --mode metadata --host 127.0.0.1 --port 18003
+```
+
+## 6) Systemd hardening on Linux (production)
+
+```bash
+sudo env ZOCKET_HOME=/var/lib/zocket zocket harden install-linux-system \
+  --service-user zocketd \
+  --zocket-home /var/lib/zocket \
+  --web-port 18001 \
+  --mcp-host 127.0.0.1 \
+  --mcp-port 18002 \
+  --mcp-mode metadata
+```
+
+Check:
+```bash
+systemctl status zocket-web.service --no-pager
+systemctl status zocket-mcp-http.service --no-pager
+systemctl status zocket-mcp-http-streamable.service --no-pager
+```
+
+### Optional: systemd unit for Codex (streamable HTTP on 18003)
+
+Create `/etc/systemd/system/zocket-mcp-http-streamable.service`:
+```ini
+[Unit]
+Description=Zocket MCP HTTP Streamable (system)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=zocketd
+Group=zocketd
+Environment=ZOCKET_HOME=/var/lib/zocket
+ExecStart=/usr/bin/python3 -m zocket mcp --transport streamable-http --mode metadata --host 127.0.0.1 --port 18003
+Restart=on-failure
+RestartSec=2
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ProtectKernelTunables=true
+ProtectControlGroups=true
+LockPersonality=true
+MemoryDenyWriteExecute=true
+ReadWritePaths=/var/lib/zocket
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now zocket-mcp-http-streamable.service
+```
+
+### Linux user-level autostart (no root)
+```bash
+zocket autostart install --target web --web-port 18001
+zocket autostart install --target mcp --mcp-port 18002 --mcp-mode metadata --mcp-host 127.0.0.1
+zocket autostart status --target both
+```
+
+### macOS launchd autostart (manual)
+Create `~/Library/LaunchAgents/dev.zocket.web.plist`, `dev.zocket.mcp-sse.plist`,
+and `dev.zocket.mcp-streamable.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>dev.zocket.web</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/Users/YOUR_USER/.local/share/zocket/venv/bin/python3</string>
+      <string>-m</string><string>zocket</string>
+      <string>web</string><string>--host</string><string>127.0.0.1</string>
+      <string>--port</string><string>18001</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>ZOCKET_HOME</key><string>/Users/YOUR_USER/.zocket</string>
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+  </dict>
+</plist>
+```
+
+SSE MCP (`dev.zocket.mcp-sse.plist`):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>dev.zocket.mcp-sse</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/Users/YOUR_USER/.local/share/zocket/venv/bin/python3</string>
+      <string>-m</string><string>zocket</string>
+      <string>mcp</string><string>--transport</string><string>sse</string>
+      <string>--mode</string><string>metadata</string>
+      <string>--host</string><string>127.0.0.1</string>
+      <string>--port</string><string>18002</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>ZOCKET_HOME</key><string>/Users/YOUR_USER/.zocket</string>
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+  </dict>
+</plist>
+```
+
+Streamable HTTP MCP (`dev.zocket.mcp-streamable.plist`):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>dev.zocket.mcp-streamable</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/Users/YOUR_USER/.local/share/zocket/venv/bin/python3</string>
+      <string>-m</string><string>zocket</string>
+      <string>mcp</string><string>--transport</string><string>streamable-http</string>
+      <string>--mode</string><string>metadata</string>
+      <string>--host</string><string>127.0.0.1</string>
+      <string>--port</string><string>18003</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>ZOCKET_HOME</key><string>/Users/YOUR_USER/.zocket</string>
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+  </dict>
+</plist>
+```
+
+Load services:
+```bash
+launchctl load ~/Library/LaunchAgents/dev.zocket.web.plist
+launchctl load ~/Library/LaunchAgents/dev.zocket.mcp-sse.plist
+launchctl load ~/Library/LaunchAgents/dev.zocket.mcp-streamable.plist
+```
+
+### Windows autostart (Task Scheduler)
+Installer can create tasks with:
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install-zocket.ps1 -EnableAutostart
+```
+
+Or create manually:
+- task `ZocketWeb` on logon
+- task `ZocketMcpSse` on logon
+- task `ZocketMcpStreamable` on logon
+- actions:
+  - `python -m zocket web --host 127.0.0.1 --port 18001`
+  - `python -m zocket mcp --transport sse --mode metadata --host 127.0.0.1 --port 18002`
+  - `python -m zocket mcp --transport streamable-http --mode metadata --host 127.0.0.1 --port 18003`
+
+## 7) First web open
+
+Open `http://127.0.0.1:18001` and choose one:
+- set your own password
+- generate strong password
+- continue without password (explicit warning + confirmation)
+
+## 8) Health checks
+
+```bash
+curl -I http://127.0.0.1:18001/login
+curl -I http://127.0.0.1:18002/sse
+curl -I http://127.0.0.1:18003/mcp
+zocket mcp --transport stdio --mode metadata
+```