@neosmart/ssclient 2.0.0

package/README.md

@@ -0,0 +1,99 @@
+# `ssclient`, the SecureStore CLI
+
+This npmjs package contains a universal binary installer for [`ssclient`](https://github.com/neosmart/securestore-rs/tree/master/ssclient) the rust cli companion to the open source, cross-platform, language-agnostic [SecureStore secrets management protocol](https://neosmart.net/SecureStore/).
+
+This package will attempt to automatically download and install precompiled, dependency-free binaries for your os/architecture via the npmjs package repos. Please refer to the [`ssclient` documentation](https://github.com/neosmart/securestore-rs/tree/master/ssclient) for more information on the use of `ssclient` to create and manage truly secure secrets containers and help put an end to `.env` madness and insecurity.
+
+## Installation
+
+This package is compatible with `npm` and `bun`, and can be installed or run directly with with `npx`/`bunx`.
+
+```sh
+npm install [--global] @neosmart/ssclient
+```
+
+or
+
+```sh
+bun --global add @neosmart/ssclient
+```
+
+Will attempt to locate, download, and install a precompiled, dependency-free `ssclient` binary for your current platform/architecture. If no such precompiled binary currently exists, a WASM-compiled version of the binary [will be deployed instead](https://neosmart.net/blog/ssclient-wasm).
+
+## Usage
+
+Please refer to the [`ssclient` documentation](https://github.com/neosmart/securestore-rs/tree/master/ssclient) for full usage information, but the following is a brief guide on creating and access secrets with the `ssclient` cli:
+
+Note that you may substitute `npx @neosmart/ssclient` or `bunx @neosmart/ssclient` for `ssclient` in the steps below if you have not globally installed `ssclient` via whatever means you prefer.
+
+### Creating a new secrets container
+
+```bash
+~> mkdir secrets/
+~> cd secrets/
+~> ssclient create --export-key secrets.key
+Password: ************
+Confirm Password: ************
+
+# Now you can use `ssclient -p` with your old password
+# or `ssclient -k secrets.key` to encrypt/decrypt with
+# the same keys.
+```
+
+### Adding secrets
+
+Secrets may be added with your password or the equivalent encryption key file, and may be specified in-line as arguments to `ssclient` or more securely at a prompt by omitting the value when calling `ssclient create`:
+
+```bash
+# ssclient defaults to password-based decryption:
+~> ssclient set aws:s3:accessId AKIAV4EXAMPLE7QWERT
+Password: *********
+```
+
+similarly:
+
+```bash
+# Use `-k secrets.key` to load the encryption key and
+# skip the prompt for the vault password:
+~> ssclient -k secrets.key set aws:s3:accessKey
+Value: v1Lp9X7mN2B5vR8zQ4tW1eY6uI0oP3aS5dF7gH9j
+```
+
+Note that in the latter example, the secret being stored was not typed into the shell (bash, fish, etc) and, as such, is not contained in/leaked by the shell history.
+
+### Retrieving secrets
+
+While you normally use one of the [SecureStore libraries for your language of choice](https://neosmart.net/SecureStore/) to load the SecureStore vault and decrypt secrets with the exported encryption/decryption key (`secrets.key`, in the example above), you can also use `ssclient` to view them at the command line:
+
+```bash
+~> ssclient get aws:s3:accessKey
+Password: *********
+v1Lp9X7mN2B5vR8zQ4tW1eY6uI0oP3aS5dF7gH9j
+```
+
+or you can export all secrets, either as text or json (again, either with the password or with the equivalent private key).
+
+```bash
+~> ssclient get --all # defaults to JSON
+Password: *********
+[
+  {
+    "key": "aws:s3:accessId",
+    "value": "AKIAV4EXAMPLE7QWERT"
+  },
+  {
+    "key": "aws:s3:accessKey",
+    "value": "v1Lp9X7mN2B5vR8zQ4tW1eY6uI0oP3aS5dF7gH9j"
+  }
+]
+```
+
+or
+
+```bash
+~> ssclient get --key secrets.key -a --format text
+aws:s3:accessId:AKIAV4EXAMPLE7QWERT
+aws:s3:accessKey:v1Lp9X7mN2B5vR8zQ4tW1eY6uI0oP3aS5dF7gH9j
+```
+
+Please refer to the [`ssclient` documentation](https://github.com/neosmart/securestore-rs/tree/master/ssclient) for full usage information.

package/bin/ssclient.cmd

@@ -0,0 +1 @@
+This placeholder file will be overridden by our install scripts

package/build.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+// @ts-check
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const cargoRoot = path.resolve(__dirname, '..', '..');
+const srcWasm = path.resolve(cargoRoot, 'target/wasm32-wasip1/release/ssclient.wasm');
+const dstDir = path.resolve(__dirname, 'bin');
+const dstWasm = path.resolve(dstDir, 'ssclient.wasm');
+const ssclient = path.resolve(__dirname, 'ssclient.js');
+
+/**
+ * Helper to exit with a non-zero status code
+ * @param {string} message
+ */
+const die = (message) => {
+  console.error(`[BUILD ERROR] ${message}`);
+  process.exit(1);
+};
+
+console.log(`> cd ${cargoRoot}`);
+
+/** @type {import('node:child_process').SpawnSyncOptions} */
+const spawnOptions = {
+  cwd: cargoRoot,
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    RUSTFLAGS: '', // Explicitly clear RUSTFLAGS
+  },
+  shell: false
+};
+
+const cargoArgs = [
+  'build',
+  '--no-default-features',
+  '--features', 'rustls',
+  '--target', 'wasm32-wasip1',
+  '--release'
+];
+
+console.log(`> cargo ${cargoArgs.join(' ')}`);
+
+const result = spawnSync('cargo', cargoArgs, spawnOptions);
+
+if (result.error) {
+  die(`Failed to execute cargo: ${result.error.message}`);
+}
+
+if (result.status !== 0) {
+  die(`Cargo build failed with exit code ${result.status}`);
+}
+
+try {
+  if (!fs.existsSync(dstDir)) {
+    console.log(`Creating directory: ${dstDir}`);
+    fs.mkdirSync(dstDir, { recursive: true });
+  }
+
+  console.log(`Copying build artifact:\n From: ${srcWasm}\n To:   ${dstWasm}`);
+
+  if (!fs.existsSync(srcWasm)) {
+    die(`Source file not found at ${srcWasm}`);
+  }
+
+  fs.copyFileSync(srcWasm, dstWasm);
+  console.log('Build and copy successful.');
+} catch (err) {
+  /** @type {Error} */
+  // @ts-ignore
+  const error = err;
+  die(`File operation failed: ${error.message}`);
+}
+
+// Ensure ssclient.js runs ok
+const wasmResult = spawnSync('node', [ssclient, "--version"]);
+if (wasmResult.error) {
+  die(`Failed to execute ssclient.wasm (via ssclient.js): ${wasmResult.error.message}`);
+} else if (wasmResult.status !== 0) {
+  die(`ssclient.wasm failed with exit code ${wasmResult.status}`);
+}

package/install.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+
+// @ts-check
+"use strict";
+
+import { mkdir, rm, rename, unlink, symlink, copyFile, chmod, readdir, readFile, writeFile } from "node:fs/promises";
+import { createWriteStream, existsSync } from "node:fs";
+import { finished } from 'node:stream/promises';
+import { join, relative, basename, dirname } from "node:path";
+import { execSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from 'node:url';
+import pkg from "./package.json" with { type: "json" };
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * @typedef {Object} BuildEntry
+ * @property {string | string[]} url - One or more URLs to try
+ * @property {string} [bin_path] - Override default bin_path
+ */
+
+/**
+ * @typedef {Object} Manifest
+ * @property {string} bin_path - Default path to entrypoint within archives
+ * @property {Record<string, string | string[] | BuildEntry>} precompiled - Mapping of os-arch to builds
+ */
+
+const MANIFEST_URLS = [
+  `${__dirname}/manifest.json`,
+  `https://raw.githubusercontent.com/neosmart/securestore-rs/refs/heads/master/ssclient/npm/manifests/v${pkg.version}.json`,
+  `https://neosmart.net/SecureStore/ssclient/npm/manifests/v${pkg.version}.json`,
+  `https://raw.githubusercontent.com/neosmart/securestore-rs/refs/tags/ssclient/${pkg.version}/ssclient/npm/manifests/v${pkg.version}.json`,
+];
+const BIN_NAME = "ssclient";
+const PKG_ROOT = __dirname;
+const FALLBACK_JS = join(PKG_ROOT, "ssclient.js");
+const BASE_BIN_DIR = join(PKG_ROOT, "bin");
+const VERSION = pkg.version;
+const VERSIONED_DIR = join(BASE_BIN_DIR, `v${VERSION}`);
+const ENTRY_POINT = join(__dirname, pkg.bin[BIN_NAME]);
+
+/** @returns {string} */
+function getPlatformTuple() {
+  return `${process.platform}-${process.arch}`;
+}
+
+/** @param {string} urlStr @returns "string" */
+function extractUrlFileName(urlStr) {
+  if (urlStr.startsWith('http')) {
+    const urlPath = new URL(urlStr).pathname;
+    return /[^/]+$/.exec(urlPath)?.[0] ?? urlPath;
+  }
+  const fname = /[^/\\]+$/.exec(urlStr)?.[0];
+  if (fname) {
+    return fname;
+  }
+  throw new Error(`Could not extract file name from "${urlStr}"`);
+}
+
+/** @param {string} urlStr @returns {"zip" | "tar"} */
+function getArchiveType(urlStr) {
+  const fname = extractUrlFileName(urlStr);
+  if (fname.endsWith(".zip")) return "zip";
+  if (/\.tar(\.[^.]+)?$|\.tgz$/.test(fname)) return "tar";
+  throw new Error(`Unsupported archive type for ${fname}`);
+}
+
+/**
+ * Executes a callback when the variable goes out of scope.
+ * @param {() => void} callback
+ * @returns {Disposable}
+ */
+export const defer = (callback) => ({
+  [Symbol.dispose]: callback
+});
+
+/**
+ * Tries to download from an array of URLs.
+ * @param {string[]} urls
+ * @param {string} dest
+ */
+async function downloadWithRetry(urls, dest) {
+  const urlArray = Array.isArray(urls) ? urls : [urls];
+  let lastErr;
+
+  for (const url of urlArray) {
+    try {
+      console.log(`Downloading: ${url}`);
+      if (/^https?:/.test(url)) {
+        return await download(url, dest);
+      } else if (existsSync(url)) {
+        return await copyFile(url, dest);
+      }
+      throw new Error(`Path not found: ${url}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : err?.toString();
+      console.warn(`Failed to download from ${url}: ${msg}`);
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * @param {string | URL} url
+ * @param {import("node:fs").PathLike} dest
+ */
+async function download(url, dest) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  if (!response.body) {
+      throw new Error("Invalid response body");
+  }
+
+  const fileStream = createWriteStream(dest);
+  const reader = response.body.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    fileStream.write(value);
+  }
+  fileStream.end();
+  return finished(fileStream);
+}
+
+/**
+ * Atomic extraction into the versioned folder.
+ * @param {string} archivePath
+ * @param {string} binPath - Path to the binary within the archive
+ * @returns {Promise<{dir: string, bin: string}>} - Path to the extracted release directory and binary
+ */
+async function extractRelease(archivePath, binPath) {
+  const archiveType = getArchiveType(archivePath);
+  console.log(`Extracting ${archiveType}...`);
+
+  const stagingDir = join(BASE_BIN_DIR, `.staging-${randomBytes(4).toString("hex")}`);
+  await mkdir(stagingDir, { recursive: true });
+
+  if (archiveType === "tar") {
+    try {
+      execSync(`tar -xf "${archivePath}" -C "${stagingDir}"`);
+    }
+    catch (err) {
+      if (process.platform === "win32") {
+        throw new Error(`Unsupported archive type for platform ${process.platform}`);
+      }
+      throw err;
+    }
+  } else {
+    if (process.platform === "win32") {
+      execSync(`powershell -command "Expand-Archive -Path '${archivePath}' -DestinationPath '${stagingDir}'"`);
+    } else {
+      execSync(`unzip "${archivePath}" -d "${stagingDir}"`);
+    }
+  }
+
+  // Add Windows .exe suffix if not accounted for in manifest
+  let sourcePath = join(stagingDir, binPath);
+  if (process.platform === "win32" && !sourcePath.endsWith(".exe")) {
+    if (!existsSync(sourcePath) && existsSync(sourcePath + ".exe")) {
+      sourcePath += ".exe";
+    }
+  }
+
+  // Atomically move staging to versioned dir
+  if (existsSync(VERSIONED_DIR)) {
+    await rm(VERSIONED_DIR, { recursive: true });
+  }
+  await rename(stagingDir, VERSIONED_DIR);
+
+  let bin = join(VERSIONED_DIR, binPath);
+  if (process.platform === "win32" && !sourcePath.endsWith(".exe")) {
+    if (!existsSync(bin) && existsSync(bin + ".exe")) {
+      bin += ".exe";
+    }
+  }
+
+  return {
+    dir: VERSIONED_DIR,
+    bin,
+  }
+}
+
+/**
+ * Creates a symlink or copies the file, dependent on platform.
+ * @param {string} target
+ * @param {string} linkPath
+ */
+async function linkBinary(target, linkPath) {
+  try {
+    // Don't check if it exists first because we need to also remove broken symlinks
+    await unlink(linkPath);
+  } catch (err) {
+    console.error(`Failed to remove existing binary: ${err}`);
+    throw err;
+  }
+
+  const rel = relative(dirname(linkPath), target);
+  if (process.platform === "win32") {
+    const runner = `@ECHO OFF\nSETLOCAL\n"%~dp0${rel}" %*`;
+    await writeFile(linkPath, runner, "utf8");
+  } else {
+    // *nix: Always create relative symlink
+    await symlink(rel, linkPath);
+    await chmod(target, 0o755);
+  }
+}
+
+async function removeOldVersions() {
+  const items = await readdir(BASE_BIN_DIR);
+  const currentName = basename(VERSIONED_DIR);
+  for (const item of items) {
+    if (item.startsWith(`v`) && item !== currentName) {
+      await rm(join(BASE_BIN_DIR, item), { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+/**
+* @overload
+* @param {string | URL} pathOrUrl
+* @param {"text"} result
+* @returns {Promise<string>}
+*/
+/**
+* @overload
+* @param {string | URL} pathOrUrl
+* @param {"json"} result
+* @returns {Promise<any>}
+*/
+/**
+* @param {string | URL} pathOrUrl
+* @param {"text" | "json"} result
+* @returns {Promise<string | any>}
+*/
+async function resolve(pathOrUrl, result) {
+  if (/^https?:/.test(pathOrUrl.toString())) {
+    const response = await fetch(pathOrUrl);
+    if (!response.ok) {
+      throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+    }
+    return result === "text" ? await response.text() : await response.json();
+  } else if (existsSync(pathOrUrl)) {
+    const text = await readFile(pathOrUrl, { encoding: "utf8" });
+    return result === "text" ? text : JSON.parse(text);
+  } else {
+    throw new Error(`Unable to resolve path/url ${pathOrUrl}`);
+  }
+}
+
+async function main() {
+  let downgradeError = false;
+  try {
+    await mkdir(BASE_BIN_DIR, { recursive: true });
+
+    console.log("Fetching manifest...");
+
+    /** @type {Manifest} */
+    const manifest = await (async () => {
+      for (const url of MANIFEST_URLS) {
+        try {
+          const manifest = await resolve(url, "json");
+          return manifest;
+        } catch {
+          continue;
+        }
+      }
+      throw new Error("Unable to load application manifest");
+    })();
+    const tuple = getPlatformTuple();
+    const entry = manifest.precompiled[tuple];
+
+    if (!entry) {
+      downgradeError = true;
+      throw new Error(`Precompiled binaries for ${tuple} not found`);
+    }
+
+    // Normalize manifest entry:
+    // We allow tuples to point to either a "url like" (url or array of urls)
+    // or an object containing a bin_path override + a "url like".
+    const urls = (typeof entry === "string" ? [entry] : Array.isArray(entry) ? entry : (Array.isArray(entry.url) ? entry.url : [entry.url]))
+      .filter(url => !!url);
+    const binPathInside = (typeof entry === "object" && !Array.isArray(entry) && entry.bin_path) || manifest.bin_path;
+
+    if (!urls[0]) {
+        throw new Error(`Missing a url for target ${tuple}`);
+    }
+    const archivePath = join(tmpdir(), extractUrlFileName(urls[0]));
+    using _ = defer(async () => {
+      if (existsSync(archivePath)) {
+        await rm(archivePath);
+      }
+    });
+    await downloadWithRetry(urls, archivePath);
+
+    const { bin} = await extractRelease(archivePath, binPathInside);
+
+    await linkBinary(bin, ENTRY_POINT);
+    await removeOldVersions();
+
+    console.log(`Success: Installed precompiled native ${tuple} ${BIN_NAME}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : err?.toString();
+    if (downgradeError) {
+      console.info(msg);
+    } else {
+      console.warn(`Binary installation failed: ${msg}.`);
+    }
+
+    console.info(`Falling back to wasm ${BIN_NAME}...`);
+
+    if (existsSync(ENTRY_POINT)) {
+      await unlink(ENTRY_POINT);
+    }
+    if (process.platform !== "win32") {
+      await linkBinary(FALLBACK_JS, ENTRY_POINT);
+    } else {
+      const rel = relative(dirname(ENTRY_POINT), FALLBACK_JS);
+      console.debug({
+        rel,
+          ENTRY_POINT,
+          FALLBACK_JS,
+      });
+      const runner = `@ECHO OFF\nSETLOCAL\nnode --experimental-wasi-unstable-preview1 "%~dp0${rel}" %*`;
+      await writeFile(ENTRY_POINT, runner, "utf8");
+    }
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@neosmart/ssclient",
+  "description": "SecureStore cli client, cross-platform and sandboxed",
+  "version": "2.0.0",
+  "keywords": [
+    "SecureStore",
+    "encryption",
+    "secrets"
+  ],
+  "homepage": "https://neosmart.net/SecureStore/",
+  "bugs": "https://github.com/neosmart/securestore-rs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neosmart/securestore-rs.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Mahmoud Al-Qudsi",
+    "email": "mqudsi@neosmart.net",
+    "url": "https://github.com/mqudsi"
+  },
+  "funding": "https://mqudsi.com/donate/",
+  "bin": {
+    "ssclient": "bin/ssclient.cmd"
+  },
+  "files": [
+    "./README.md",
+    "./bin/ssclient.cmd",
+    "./bin/ssclient.wasm",
+    "./build.js",
+    "./install.js",
+    "./ssclient.js",
+    "./tsconfig.js"
+  ],
+  "type": "module",
+  "scripts": {
+    "prepublishOnly": "npm run lint && npm run build",
+    "prepare": "echo 'This placeholder file will be overridden by our install scripts' > bin/ssclient.cmd",
+    "install": "node ./install.js",
+    "ssclient": "node ./ssclient.js",
+    "build": "node ./build.js",
+    "lint": "tsc"
+  },
+  "devDependecies": [
+    "@types/node"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.2"
+  }
+}

package/ssclient.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from 'node:url';
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const WASM_FILE = join(__dirname, "bin/ssclient.wasm");
+
+// Silence node warnings about WASI being in preview, as we test functionality ourselves
+if (process && process.emitWarning) {
+    const emitWarning = process.emitWarning;
+    process.emitWarning = (warning, type) => {
+        if (type === "ExperimentalWarning") {
+            if (warning.toString().includes("WASI")) {
+                return false;
+            }
+        }
+        // @ts-ignore
+        return emitWarning(arguments);
+    };
+}
+
+// Import WASI dynamically to ensure our ExperimentalWarning intercept takes place first
+// Also figure out if we need to relaunch with a flag for compatibility with older node versions.
+
+/** @type {typeof import("node:wasi").WASI} */
+let WASI;
+try {
+  const wasiModule = await import("node:wasi");
+  WASI = wasiModule.WASI;
+} catch (e) {
+  // If we can't import it, we need the --experimental-wasi-unstable-preview1 flag.
+  const scriptPath = fileURLToPath(import.meta.url);
+
+  if (process.argv.find(arg => arg === "--experimental-wasi-unstable-preview1")) {
+    // Already tried launching with this flag and it didn't work
+    console.error(`Unable to load WASI module: ${e}`);
+    process.exit(1);
+  }
+
+  // Re-spawn the current process with the flag enabled
+  const child = spawn(
+    process.execPath,
+    ["--experimental-wasi-unstable-preview1", scriptPath, ...process.argv.slice(2)],
+    { stdio: "inherit" }
+  );
+
+  child.on("exit", (code) => process.exit(code ?? 0));
+  // Block indefinitely until child has exited
+  await new Promise(() => {});
+}
+
+/**
+ * @param {string} payload - Path to the WASM binary
+ */
+async function runWasm(payload) {
+    // Extract node-specific values
+    const args = process.argv.slice(2);
+    const cwd = process.cwd();
+    const env = process.env;
+
+    const wasi = new WASI({
+        version: "preview1",
+        args: ["ssclient", ...args],
+        env: env,
+        // Map paths we need into the sandbox
+        preopens: {
+            [cwd]: cwd,
+            ".": ".",
+        },
+    });
+
+    // wasi.getImportObject() isn't yet supported by bun
+    // Reported upstream at https://github.com/oven-sh/bun/issues/28534
+    /** @type {any} */
+    const wasiImportObject = wasi.getImportObject ? wasi.getImportObject()
+        : { wasi_snapshot_preview1: wasi.wasiImport };
+
+    try {
+        const wasmPath = resolve(payload);
+        const wasmBuffer = await readFile(wasmPath);
+        const wasmModule = await WebAssembly.compile(wasmBuffer);
+        const instance = await WebAssembly.instantiate(
+            wasmModule,
+            wasiImportObject,
+        );
+
+        wasi.start(instance);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : err?.toString();
+        console.error(`Error executing ${payload}: `, msg);
+        process.exit(1);
+    }
+}
+
+await runWasm(WASM_FILE);