{"id":14933,"library":"sshifu-server","title":"SSHifu Server: OAuth Gateway and Certificate Authority","description":"sshifu-server is an SSH authentication server that integrates an OAuth gateway with a certificate authority, issuing short-lived SSH certificates. It provides authentication against GitHub organizations and generic OIDC providers, including Authentik, Google Workspace, Okta, and Auth0. Currently at version 0.10.0, the project maintains an active release cadence, with several feature and bugfix releases in the past year. Key differentiators include its lightweight architecture, requiring minimal infrastructure with no external database, its seamless integration of OAuth for SSH, and its ability to act as a full certificate authority to enhance SSH security by reducing reliance on long-lived keys. The core server logic is implemented in Go, with the npm package serving as a wrapper for distribution and installation.","status":"active","version":"0.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/azophy/sshifu","tags":["javascript","ssh","certificate","oauth","github","authentication","security","server"],"install":[{"cmd":"npm install sshifu-server","lang":"bash","label":"npm"},{"cmd":"yarn add sshifu-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add sshifu-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for the npm package wrapper and installation scripts. The core server is a Go binary.","package":"node","optional":false},{"reason":"The core server is a Go application; the binary is automatically downloaded during npm install.","package":"Go binary","optional":false}],"imports":[{"note":"The `sshifu-server` package distributes a Go binary via npm. It is not intended for programmatic import as a JavaScript/TypeScript library; its primary interface is the command-line interface (CLI). Attempting to import symbols will result in module not found errors.","wrong":"import { startServer } from 'sshifu-server'","symbol":"sshifu-server command","correct":"npx sshifu-server"},{"note":"To use `sshifu-server` directly from your terminal after installation, it must be installed globally. There are no exposed JavaScript functions to `require` or `import` from the package.","wrong":"require('sshifu-server').run()","symbol":"Global CLI","correct":"npm install -g sshifu-server"},{"note":"Initial configuration for OAuth credentials and CA settings is performed interactively through the CLI when the server is first run, not via programmatic API calls.","wrong":"import { configure } from 'sshifu-server'","symbol":"Configuration","correct":"sshifu-server"}],"quickstart":{"code":"#!/usr/bin/env bash\n\n# Quick start using npx without global installation\necho \"Starting sshifu-server via npx...\"\nnpx sshifu-server\n\n# --- OR ---\n\n# Global installation for frequent use\necho \"\\nInstalling sshifu-server globally...\"\nnpm install -g sshifu-server\n\n# Run the globally installed server\necho \"\\nStarting globally installed sshifu-server...\"\nsshifu-server\n\necho \"\\nFollow the prompts to configure GitHub OAuth credentials, Certificate Authority (CA) settings, and server listen address.\"","lang":"bash","description":"Demonstrates how to quickly run sshifu-server using npx or install it globally and then run the CLI. It highlights the interactive configuration process."},"warnings":[{"fix":"Use `sshifu-server` as a command-line interface (CLI) tool. Do not attempt to import it programmatically in JS/TS code.","message":"The `sshifu-server` npm package primarily distributes a Go binary. It is not a JavaScript/TypeScript library and does not export any programmatic symbols for `import` or `require`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review the setup wizard carefully during initial configuration or when updating from older versions to ensure OIDC settings are correctly applied. Back up existing configurations if migrating.","message":"Introduction of OIDC provider support and wizard changes in `v0.7.0` and `v0.10.0` may alter how configurations are created or updated, particularly for new deployments.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Ensure you are using `sshifu-server@0.7.7` or later for reliable installation on Windows. Update npm and Node.js to recent versions.","message":"Prior to `v0.7.7`, `sshifu-server` npm package installation on Windows could fail due to incorrect archive formats and extraction logic, leading to missing binaries.","severity":"gotcha","affected_versions":"<0.7.7"},{"fix":"Verify network connectivity and proxy settings if the Go binary download fails. Ensure your Node.js version meets the `engines` requirement (>=14.0.0). Check npm logs for specific download or installation errors.","message":"The `sshifu-server` requires a Go binary (downloaded automatically) and Node.js >=14.0.0. Network issues, restrictive firewalls, or incompatible Node.js versions can cause installation failures.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install -g sshifu-server` to install the package globally, or use `npx sshifu-server` to run it without global installation.","cause":"The `sshifu-server` package was not installed globally, or the global `node_modules` bin directory is not in your system's PATH.","error":"Error: command not found: sshifu-server"},{"fix":"Check your network connection and proxy settings. Ensure you have write permissions in your npm global installation directory. On Windows, ensure you are on `sshifu-server@0.7.7` or newer and that PowerShell's `Expand-Archive` command is available.","cause":"This error often indicates issues with downloading the Go binary, corrupt archives, or insufficient permissions for extraction, especially on Windows or restricted environments.","error":"npm ERR! Failed to extract sshifu-server binary from archive"},{"fix":"Remove `require('sshifu-server')` or `import ... from 'sshifu-server'` statements. Instead, interact with `sshifu-server` via its command-line interface: `npx sshifu-server` or `sshifu-server` if installed globally.","cause":"Attempting to `require()` or `import` `sshifu-server` as a JavaScript/TypeScript library. This package is a CLI tool distributing a Go binary, not a JS module.","error":"Error: Cannot find module 'sshifu-server'"}],"ecosystem":"npm"}