@dalyem/hopkey 0.0.0-stage → 0.1.0-rc.3

package/LICENSE

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

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @dalyem/hopkey
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `hop` command of [HopKey](https://github.com/dalyem/HopKey), an end-to-end encrypted vault for SSH hosts and keys. `hop` is a Go program; this package is only a way to get it.
+
+```
+npm i -g @dalyem/hopkey          # a release
+npm i -g @dalyem/hopkey@next     # the latest prerelease
+```
+
+Linux and macOS, on x64 and arm64, with Node 18 or later for the install. The package holds all four builds and downloads nothing when it installs. The server, `hop-server`, is a Docker image: `docker pull ghcr.io/dalyem/hop-server:VERSION`.
+
+## What `hop` is after the install
+
+The package's postinstall copies the build for your platform over `bin/hop`, so `hop` on your PATH is the native binary: no Node when it runs, and its signals and exit codes are its own. The package contains a small Node launcher at `bin/hop` for installs that skip postinstall scripts (`npm i -g --ignore-scripts`, pnpm and bun by default). The launcher starts `vendor/<os>-<arch>/hop`, passes stdin, stdout and stderr straight through, and exits with hop's exit code, or with hop's signal. It forwards SIGTERM. It does not forward SIGINT or SIGHUP: the terminal already sends those to hop, and a second one makes hop quit at once.
+
+One thing the launcher cannot do: a `nohup hop ...` that should ignore hangups does not, because Node starts its child with default signal handling. If that matters, run the native binary: reinstall without `--ignore-scripts`, or run `vendor/<os>-<arch>/hop` from the package directory (`$(npm root -g)/@dalyem/hopkey`).
+
+If the postinstall cannot replace `bin/hop` for any reason, it says nothing, the install still succeeds, and the launcher stays.
+
+## Upgrading
+
+A running `hop daemon` keeps running the code it started with. After an upgrade, run `hop daemon stop`; the next hop command starts the new one. The login service (`hop setup --service`) and the MCP client entries (`hop mcp install`) name the path of the `hop` file. If an upgrade or a different Node version (nvm, say) changes that path, run `hop setup --service` and `hop mcp install` again.
+
+More in the [HopKey README](https://github.com/dalyem/HopKey#readme).

package/bin/hop

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+// Fallback for installs whose postinstall did not run; see lib/shim.js.
+require('../lib/shim.js').run({
+  platform: process.platform,
+  arch: process.arch,
+  argv: process.argv.slice(2),
+});

package/install.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// postinstall: put the native hop binary where bin/hop is, so that `hop` on
+// PATH is the Go binary itself and not a Node launcher: exact signals, exact
+// exit codes, no Node at runtime, and the same file hop finds for itself
+// (os.Executable, os.SameFile) when it starts its daemon or writes a service
+// unit or an MCP client entry.
+//
+// This is an optimisation, and never a reason for the install to fail. If
+// anything goes wrong it leaves the shim (lib/shim.js) in place, prints
+// nothing and exits 0. It makes no network request: the binaries are in the
+// package, under vendor/.
+
+const fs = require('fs');
+const path = require('path');
+const { resolveBinary } = require('./lib/platform.js');
+
+// install copies the binary for this platform over bin/hop, through a temp
+// file in the same directory and a rename. Overwriting bin/hop in place would
+// keep its inode, and on macOS arm64 a changed signed binary on an old inode
+// can get the process killed. It returns whether bin/hop was replaced.
+function install({ root, platform, arch }) {
+  const found = resolveBinary({ root, platform, arch });
+  if (found.error) {
+    return false;
+  }
+  const bin = path.join(root, 'bin');
+  const dest = path.join(bin, 'hop');
+  const tmp = path.join(bin, `.hop.${process.pid}.tmp`);
+  try {
+    fs.copyFileSync(found.path, tmp);
+    fs.chmodSync(tmp, 0o755);
+    fs.renameSync(tmp, dest);
+    return true;
+  } catch (e) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (e2) {
+      // It may not have been made.
+    }
+    return false;
+  }
+}
+
+module.exports = { install };
+
+if (require.main === module) {
+  try {
+    install({ root: __dirname, platform: process.platform, arch: process.arch });
+  } catch (e) {
+    // Leave the shim.
+  }
+  process.exit(0);
+}

package/lib/platform.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Where the hop binary for a platform lives inside this package. The shim
+// (lib/shim.js) and the postinstall (install.js) both use it.
+
+const fs = require('fs');
+const path = require('path');
+
+const PLATFORMS = ['linux', 'darwin'];
+const ARCHES = ['x64', 'arm64'];
+
+// resolveBinary returns {path} for the binary that fits platform and arch
+// (as process.platform and process.arch name them), or {error}, one line
+// of text for stderr, when there is none.
+function resolveBinary({ root, platform, arch }) {
+  if (!PLATFORMS.includes(platform) || !ARCHES.includes(arch)) {
+    return {
+      error: `hop: no hop binary for ${platform}-${arch}; the @dalyem/hopkey package ships linux and darwin, on x64 and arm64`,
+    };
+  }
+  const file = path.join(root, 'vendor', `${platform}-${arch}`, 'hop');
+  let st;
+  try {
+    st = fs.statSync(file);
+  } catch (e) {
+    st = null;
+  }
+  if (!st || !st.isFile()) {
+    return { error: `hop: the binary for ${platform}-${arch} is missing from this install (${file}); reinstall the @dalyem/hopkey package` };
+  }
+  return { path: file };
+}
+
+module.exports = { resolveBinary };

package/lib/shim.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// The fallback launcher behind bin/hop. A normal install never reaches it:
+// install.js (postinstall) replaces bin/hop with the native binary, so hop
+// runs with no Node in between. The shim is what runs when the postinstall
+// did not: npm --ignore-scripts, pnpm and bun, which skip it by default.
+//
+// It stays out of hop's way:
+//   - stdio is inherited, so the shim never reads or writes hop's stdin or
+//     stdout (hop mcp speaks MCP on them, and --json must stay pure), and
+//     it writes to stderr only to say it cannot start hop.
+//   - hop's exit code is passed on as it is; a child killed by a signal is
+//     reported by killing this process with the same signal.
+//   - SIGTERM is forwarded. SIGINT and SIGHUP are not: the terminal sends
+//     them to the whole foreground process group, hop included, and hop
+//     exits at once on a second one without restoring the terminal. They
+//     are caught here only so that Node does not die first and leave hop
+//     running in the shell's background.
+//
+// Known limit: libuv resets every signal to its default in the child, so a
+// SIGHUP that was ignored when the shim started (nohup hop ...) is not
+// ignored in hop, which respects an ignored SIGHUP only when it starts
+// that way. Under the shim, a nohup'd hop dies on hangup. Run the native
+// binary (a normal install, or the file in vendor/) when that matters.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const { resolveBinary } = require('./platform.js');
+
+const EXIT_FAILURE = 255; // hop's own code for its failures
+
+// say writes one line to stderr. It uses the file descriptor directly:
+// touching process.stderr could change how the descriptor, which hop shares,
+// is set up.
+function say(line) {
+  try {
+    fs.writeSync(2, line + '\n');
+  } catch (e) {
+    // Nobody to tell.
+  }
+}
+
+function run({ root = path.resolve(__dirname, '..'), platform, arch, argv }) {
+  const found = resolveBinary({ root, platform, arch });
+  if (found.error) {
+    say(found.error);
+    process.exit(EXIT_FAILURE);
+    return;
+  }
+
+  const child = spawn(found.path, argv, { stdio: 'inherit' });
+
+  const forward = () => child.kill('SIGTERM');
+  const ignore = () => {};
+  process.on('SIGTERM', forward);
+  process.on('SIGINT', ignore);
+  process.on('SIGHUP', ignore);
+
+  child.on('error', (err) => {
+    say(`hop: cannot run ${found.path}: ${err.code || err.message}`);
+    process.exit(EXIT_FAILURE);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal === null) {
+      process.exit(code);
+      return;
+    }
+    // Hand the signal back to ourselves with our handlers gone, so that
+    // whoever waits for us sees the same death as hop's.
+    process.removeListener('SIGTERM', forward);
+    process.removeListener('SIGINT', ignore);
+    process.removeListener('SIGHUP', ignore);
+    try {
+      process.kill(process.pid, signal);
+    } catch (e) {
+      // Fall through to the exit code the shell would report.
+    }
+    // The signal ends us at once; this runs only if it did not (one whose
+    // default action is to be ignored).
+    setTimeout(() => process.exit(128 + (os.constants.signals[signal] || 0)), 200);
+  });
+}
+
+module.exports = { run };

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@dalyem/hopkey",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.3",
+  "description": "HopKey: an end-to-end encrypted vault for SSH hosts and keys (the hop CLI)",
+  "keywords": [
+    "ssh",
+    "vault",
+    "ssh-agent",
+    "hop"
+  ],
+  "homepage": "https://github.com/dalyem/HopKey#readme",
+  "bugs": {
+    "url": "https://github.com/dalyem/HopKey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dalyem/HopKey.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "hop": "bin/hop"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "bin/hop",
+    "install.js",
+    "lib/",
+    "vendor/",
+    "README.md"
+  ],
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}