srvgov-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JiangHe12
+
+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,161 @@
+# srvgov-cli
+
+[English](README.md) | [中文](README_zh.md)
+
+Governed remote server command execution for AI agents and operators. `srvgov`
+combines fail-closed command classification, R0-R3 authorization, strict TOFU
+SSH host-key pinning, output redaction, and structured audit records.
+
+## Install
+
+```bash
+npm install -g srvgov-cli
+# or
+go install github.com/JiangHe12/srvgov-cli@latest
+```
+
+GitHub Releases provide Linux, macOS, and Windows binaries for amd64 and arm64.
+The npm package downloads the matching release binary and verifies SHA-256
+checksums by default.
+
+## Quickstart
+
+```bash
+srvgov ctx set dev --server ssh://alice@example.com:22 --identity-file ~/.ssh/id_ed25519 -o json
+srvgov ctx use dev -o json
+srvgov exec --dry-run "uptime" -o json
+srvgov exec "uptime" -o json
+srvgov audit --limit 20 -o json
+```
+
+Use `-o json` for automation and AI agents.
+
+## Governance Model
+
+| Risk | Meaning | Authorization |
+|---|---|---|
+| R0 | known read-only command | free to run, still audited |
+| R1 | known benign change | `--reason` and `--yes` |
+| R2 | unknown or elevated command | `--reason`, non-empty `--ticket`, and `--yes` |
+| R3 | destructive, privileged, dynamic, or parser-uncertain command | `--reason`, `--ticket`, `--allow-destructive`, and `--yes` |
+
+Protected contexts raise R1 to R2 and R2 to R3. AI agents must never auto-fill
+`--ticket`, `--allow-destructive`, or high-risk `--yes`. Use `exec --dry-run`
+to obtain the classifier's risk and required authorization; do not guess impact.
+
+## Contexts
+
+```bash
+srvgov ctx set prod \
+  --server ssh://deploy@example.com:22 \
+  --identity-file ~/.ssh/id_ed25519 \
+  --auth-method private-key,agent,password \
+  --env production \
+  --protected \
+  -o json
+
+srvgov ctx use prod -o json
+srvgov ctx current -o json
+srvgov ctx list -o json
+srvgov ctx delete old-host -o json
+srvgov ctx role set prod --target-operator alice --role writer -o json
+srvgov ctx role list prod -o json
+srvgov ctx export prod > prod.ctx.yaml
+srvgov ctx import -f prod.ctx.yaml --rename prod-copy --yes -o json
+srvgov ctx migrate-credentials --to encrypted-file --context prod -o json
+```
+
+Context output never includes passwords, private-key contents, passphrases, or
+identity-file paths.
+
+Portable context export uses `srvgov.io/ctx-export/v1`. Literal password and
+SSH identity passphrase values are redacted by default; credstore references are
+preserved. `--include-credentials` is limited to plain-yaml contexts.
+
+## Governed Execution
+
+Preview without connecting or executing:
+
+```bash
+srvgov exec --dry-run "touch /tmp/deploy-ready" -o json
+```
+
+Execute according to the reported tier:
+
+```bash
+# R0
+srvgov exec "systemctl status nginx" -o json
+
+# R1
+srvgov exec "touch /tmp/deploy-ready" \
+  --reason "mark deployment ready" --yes -o json
+
+# R2
+srvgov exec "custom-maintenance-command" \
+  --reason "scheduled maintenance" --ticket OPS-123 --yes -o json
+
+# R3
+srvgov exec "rm -rf /tmp/old-release" \
+  --reason "remove failed release" \
+  --ticket OPS-123 --allow-destructive --yes -o json
+```
+
+Commands run without a PTY. stdout, stderr, command text, and audit fields are
+redacted before output or persistence. A remote non-zero exit returns structured
+output and process exit code 7 (`BACKEND_ERROR`).
+
+## SSH Trust And Credentials
+
+The first connection to an unknown `host:port` pins its SSH public key in
+`~/.srvgov/known_hosts`. Later key mismatches, including an unpinned key type
+for an already known address, are rejected. Host-key rotation requires manual
+review and removal of the old pin; there is no insecure bypass.
+
+Authentication order is private key, SSH agent, then password, subject to the
+context's `--auth-method` preference. Passwords and key passphrases may use
+opskit-core credential-store references. Credentials and raw SSH output are not
+logged by the transport.
+
+## Audit And Diagnostics
+
+```bash
+srvgov capabilities -o json
+srvgov audit query -o json
+srvgov audit query --type authorization.denied --status denied -o json
+srvgov audit verify --strict -o json
+srvgov audit prune --keep-last 20 -o json
+srvgov doctor -o json
+srvgov version -o json
+srvgov --version
+```
+
+Audit records live at `~/.srvgov/audit.log` by default and include effective
+risk, authorization status, target, redacted command/output, exit code, and
+error details.
+
+`capabilities` reports the current command surface, `srvgov.io/context/v1`,
+`srvgov.io/audit/v1`, R0-R3 authorization rules, `--allow-destructive`, JSONL
+audit, RBAC reader/writer/admin, dry-run, strict TOFU, and redaction.
+
+## AI Skill
+
+```bash
+srvgov install claude --skills
+srvgov install codex --skills
+srvgov install /custom/skills/path --skills
+```
+
+## Build
+
+```bash
+go build ./...
+go test -count=1 ./...
+gofmt -l main.go cmd internal
+golangci-lint run --timeout=5m
+go vet -tags=integration ./...
+```
+
+## Contributing, Security, License
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
+[LICENSE](LICENSE).

package/bin/srvgov-cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+function getBinaryPath() {
+  const binaryName = os.platform() === 'win32' ? 'srvgov.exe' : 'srvgov';
+  return path.join(__dirname, binaryName);
+}
+
+function main() {
+  const binaryPath = getBinaryPath();
+  if (!fs.existsSync(binaryPath)) {
+    console.error('srvgov binary not found. Please reinstall:');
+    console.error('  npm install -g srvgov-cli');
+    process.exit(1);
+  }
+
+  const child = spawn(binaryPath, process.argv.slice(2), { stdio: 'inherit' });
+  child.on('error', (err) => {
+    console.error('Failed to run srvgov:', err.message);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code == null ? 1 : code);
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "srvgov-cli",
+  "version": "0.1.0",
+  "description": "Governed remote server command execution CLI for AI agents",
+  "bin": {
+    "srvgov": "bin/srvgov-cli.js",
+    "srvgov-cli": "bin/srvgov-cli.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "keywords": [
+    "ssh",
+    "server",
+    "cli",
+    "ai",
+    "governance"
+  ],
+  "author": "JiangHe12",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JiangHe12/srvgov-cli.git"
+  },
+  "homepage": "https://github.com/JiangHe12/srvgov-cli",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+const crypto = require('crypto');
+const { URL } = require('url');
+
+const pkg = require('../package.json');
+const VERSION = pkg.version;
+const REPO = 'JiangHe12/srvgov-cli';
+const TIMEOUT_MS = 30000;
+
+const ALLOWED_REDIRECT_HOSTS = new Set([
+  'github.com',
+  'objects.githubusercontent.com',
+  'github-releases.githubusercontent.com',
+  'release-assets.githubusercontent.com',
+  'github.githubassets.com',
+  'cdn.jsdelivr.net',
+  'fastly.jsdelivr.net',
+]);
+
+function isAllowedRedirectHost(urlStr) {
+  try {
+    const parsed = new URL(urlStr);
+    return ALLOWED_REDIRECT_HOSTS.has(parsed.hostname) || parsed.hostname.endsWith('.github.io');
+  } catch {
+    return false;
+  }
+}
+
+function applyMirror(canonicalUrl) {
+  const mirror = process.env.SRVGOV_CLI_DOWNLOAD_MIRROR;
+  if (!mirror) return canonicalUrl;
+  return mirror.replace(/\/+$/, '') + '/' + canonicalUrl;
+}
+
+function pickClient(url) {
+  return new URL(url).protocol === 'http:' ? http : https;
+}
+
+function getPlatform() {
+  const platformMap = { win32: 'windows', darwin: 'darwin', linux: 'linux' };
+  const archMap = { x64: 'amd64', arm64: 'arm64' };
+  return {
+    os: platformMap[process.platform] || process.platform,
+    arch: archMap[process.arch] || process.arch,
+  };
+}
+
+function getBinaryName() {
+  const { os, arch } = getPlatform();
+  const ext = os === 'windows' ? '.exe' : '';
+  return `srvgov-cli-${os}-${arch}${ext}`;
+}
+
+function getDownloadUrl() {
+  const binary = getBinaryName();
+  return applyMirror(`https://github.com/${REPO}/releases/download/v${VERSION}/${binary}`);
+}
+
+function request(url, onResponse) {
+  const req = pickClient(url).get(url, onResponse);
+  req.setTimeout(TIMEOUT_MS, () => {
+    req.destroy(new Error(`Download timed out after ${TIMEOUT_MS / 1000}s`));
+  });
+  return req;
+}
+
+function redirectTarget(currentUrl, response) {
+  return new URL(response.headers.location, currentUrl).toString();
+}
+
+function download(url, dest, redirectCount = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirectCount > 5) {
+      reject(new Error('Too many redirects'));
+      return;
+    }
+
+    const req = request(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302 ||
+          response.statusCode === 307 || response.statusCode === 308) {
+        response.resume();
+        const target = redirectTarget(url, response);
+        if (!isAllowedRedirectHost(target)) {
+          reject(new Error(`Redirect to non-allowed host rejected: ${target}`));
+          return;
+        }
+        download(target, dest, redirectCount + 1).then(resolve).catch(reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(dest);
+      response.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', (err) => {
+        response.destroy();
+        fs.unlink(dest, () => {});
+        reject(err);
+      });
+    });
+    req.on('error', (err) => {
+      fs.unlink(dest, () => {});
+      reject(err);
+    });
+  });
+}
+
+function getChecksumsUrl() {
+  return `https://github.com/${REPO}/releases/download/v${VERSION}/checksums.txt`;
+}
+
+function downloadToString(url, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const req = request(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302 ||
+          response.statusCode === 307 || response.statusCode === 308) {
+        response.resume();
+        if (redirectsLeft <= 0) {
+          reject(new Error('Too many redirects'));
+          return;
+        }
+        const target = redirectTarget(url, response);
+        if (!isAllowedRedirectHost(target)) {
+          reject(new Error(`Redirect to non-allowed host rejected: ${target}`));
+          return;
+        }
+        downloadToString(target, redirectsLeft - 1).then(resolve).catch(reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+      let data = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => { data += chunk; });
+      response.on('end', () => resolve(data));
+    });
+    req.on('error', reject);
+  });
+}
+
+function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    stream.on('data', (data) => hash.update(data));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+function parseChecksums(text) {
+  const checksums = {};
+  for (const line of text.split('\n')) {
+    const match = line.trim().match(/^([a-f0-9]{64})\s+\*?(.+)$/);
+    if (match) checksums[match[2]] = match[1];
+  }
+  return checksums;
+}
+
+async function verifyDownloadedBinary(binaryPath, binaryName) {
+  if (process.env.SRVGOV_CLI_SKIP_VERIFY === '1') {
+    console.log('Verification skipped (SRVGOV_CLI_SKIP_VERIFY=1)');
+    return;
+  }
+  const checksumsUrl = getChecksumsUrl();
+  let checksums;
+  try {
+    checksums = parseChecksums(await downloadToString(checksumsUrl));
+  } catch (err) {
+    throw new Error(
+      `Could not fetch canonical checksums.txt from ${checksumsUrl}: ${err.message}. ` +
+      'Set SRVGOV_CLI_SKIP_VERIFY=1 to install without checksum verification.'
+    );
+  }
+  if (!checksums[binaryName]) {
+    throw new Error(
+      `No checksum found for ${binaryName}. ` +
+      'Set SRVGOV_CLI_SKIP_VERIFY=1 to install without checksum verification.'
+    );
+  }
+  const actual = await sha256File(binaryPath);
+  if (actual !== checksums[binaryName]) {
+    try { fs.unlinkSync(binaryPath); } catch {}
+    throw new Error(
+      `SHA-256 mismatch for ${binaryName}\n` +
+      `  Expected: ${checksums[binaryName]}\n` +
+      `  Actual:   ${actual}\n` +
+      'The downloaded binary may be corrupted or tampered with.'
+    );
+  }
+  console.log('SHA-256 verification passed');
+}
+
+async function main() {
+  const { os, arch } = getPlatform();
+  const binary = getBinaryName();
+  const url = getDownloadUrl();
+  const destDir = path.join(__dirname, '..', 'bin');
+  const dest = path.join(destDir, os === 'windows' ? 'srvgov.exe' : 'srvgov');
+
+  console.log(`Installing srvgov v${VERSION} for ${os}/${arch}...`);
+  fs.mkdirSync(destDir, { recursive: true });
+
+  try {
+    await download(url, dest);
+    await verifyDownloadedBinary(dest, binary);
+    if (os !== 'windows') fs.chmodSync(dest, 0o755);
+    console.log('srvgov installed successfully!');
+  } catch (err) {
+    console.error('Failed to install srvgov:', err.message);
+    console.error('');
+    console.error('Please download manually from:');
+    console.error(`  ${url}`);
+    process.exit(1);
+  }
+}
+
+main();