vauthlogin

README

vauth-login

A Vault token, ready to use

Authenticate to Vault with your SSH agent or JWT and get the token on stdout. The encrypted cache keeps it ready for the next call. Available as a Node module and CLI, a Go module and CLI, and binaries for Windows and Linux.

Quick login

export VAULT_TOKEN=$(vauth-login)

Install

Pick whichever fits the machine in front of you:

# node
npm install -g vauth-login

# go
go install github.com/131/vauth-login/cmd/vauth-login@latest

# binary, linux
wget -O vauth-login https://github.com/131/vauth-login/releases/latest/download/vauth-login-linux-amd64
chmod +x vauth-login

# binary, windows (cmd or PowerShell)
curl.exe -fsSL -o vauth-login.exe https://github.com/131/vauth-login/releases/latest/download/vauth-login-windows-amd64.exe

The npm package carries the Node CLI and module. Windows binaries are Authenticode signed, with SHA256SUMS on every release. Check the checksum and put the binary on your PATH. The release workflow requires the signing server.

Usage

Get a token using your configured authentication and available cache:

export VAULT_TOKEN=$(vauth-login)

The token is written raw to stdout, without a trailing newline. Status goes to stderr, for example Vauth token: reused · 11h.

Force a fresh login:

vauth-login --renew

In CI, supply the trusted Vault address through the environment. Only a matching project address skips the confirmation described under Configuration:

export VAULT_ADDR=https://vault.example.test
export VAULT_TOKEN=$(vauth-login)

The Node executable is bin/vauth-login.js; Node and Go share this CLI:

vauth-login [--renew] [--version] [--help]

--version prints the package/release version and --help prints usage, both without loading project configuration or credentials. All other arguments, aliases, and --flag=value forms are rejected. SDK helpers are not CLI commands. An unavailable token is an error (exit 1).

Configuration

The first existing file wins: VAUTHRC, ./.vauthrc, then ~/.vauthrc. VAULT_ADDR supplies the default Vault address. Authentication fields support $${env.NAME} substitution from the process environment.

vault_addr: https://vault.example.test
ssh_auth:
  path: ssh
  role: developer
# Or jwt_auth: {path: jwt, role: developer, jwt: "$${env.LOGIN_JWT}"}
token_cache: true

Configuration keys: vault_addr, ssh_auth, jwt_auth, token_cache, and known_vaults.

A ./.vauthrc belongs to the project; ~/.vauthrc belongs to the user. Login or renewal to a project-selected Vault is allowed only when it is the vault_addr of ~/.vauthrc, appears in its known_vaults, or matches environment VAULT_ADDR. Otherwise the operation fails without a prompt. The environment address is trusted in memory, without rewriting ~/.vauthrc. Explicit VAUTHRC and home configuration are operator-controlled. Reusing an inherited or valid cached token is offline and does not require this address check.

# ~/.vauthrc
known_vaults:
  - https://vault.example.test
  - https://vault.partner.example

SSH authentication uses SSH_AUTH_SOCK. Without it, the native Windows binary autodiscovers the Pageant (0.75+) named pipe, then the OpenSSH agent pipe. Disk caching requires an SSH agent; JWT authentication can still work. The Node implementation uses ssh2's Pageant transport when no Windows socket is configured.

What It Does

An inherited VAULT_TOKEN is the caller's: it is returned as is, announced as Vauth token: inherited, and never looked up, renewed or written to the cache. Without it, a usable cached token is reused locally. In the last third of its lease it is renewed if renewable, otherwise replaced by a fresh login. An expired cache or a 400/403 from token lookup/renewal triggers login; other lookup/renewal failures propagate to the caller. --renew forces a fresh login.

The cache is ~/.vauth/tokens/<session-sha256>.creds, encrypted and authenticated by ssh-agent-crypt v3. The session hash and JSON payload are identical between Node and Go: either implementation can read the other's cache. Native Windows uses the Windows user's home; WSL uses the Linux user's home.

Cache encryption chooses VAUTH_USER_IDENTITY, then VAUTH_USER_MAIL, then the ssh-agent-crypt default selector. Decryption uses the fingerprint embedded in the armor. Writes use distinct temporary files and atomic replacement; normal reuse leaves the cache unchanged. Cache failures keep the token available for the current call. token_cache: false disables cache access.

Security

The selected configuration file determines the Vault origin and authentication role. Review it before permitting SSH-agent signing. Whoever controls the agent socket can decrypt its caches. Tokens are bearer credentials: keep them out of logs, shell traces and plaintext files.

API & SDK

Node module, Go module, token lifecycle, Vault HTTP transport and the test matrix: API_and_tests.md.

Security audit

Two independently produced assessments cover the functional source in commit b7fba0c, before the metadata-only patch versioning step: SECURITY_AUDIT_fable-5.1.md and SECURITY_AUDIT_gpt-6.1-sol.md.

Criterion	Codex (Claude Fable 5.1)	Codex (GPT 6.1)
✨ Coolness	15/20	17/20
Robustness	12/20	13/20
Safety	13/20	12/20

Claude's prompt explicitly announced the public ISC upstream, npm/Go/native release channels, and upcoming exposure to external users. The retained GPT assessment was completed independently on exactly the same source before that prompt refinement. Later GPT attempts, including a second pass with existing reports present but excluded from reading, were blocked without a final report. Their missing outcomes are not replaced by invented findings or scores. The reports retain their respective context and conclusions; they were not rewritten to agree.

Both identify transport and release reproducibility risks. Claude emphasizes server-provided SSH signing inputs, environment/configuration trust boundaries, and signing-pipeline exposure. GPT emphasizes plaintext HTTP, unchecked YAML traversal, and unbounded HTTP response buffering. Verified source-level findings, conditional risks, and unverified external behavior are distinguished in the individual reports. Scores are subjective assessments, not certification or a complete current vulnerability-database clearance.

Prior reports and embedded score summaries were excluded from the completed independent runs. Separate coordinator checks passed all 80 Node tests on Node 24, ESLint, Go vet/race tests, Windows compilation, and Node/Go CLI output comparisons. Review-only module-cache copies are not part of this repository or its published package.

Credits

• François Leurent/131
• OpenAI Codex (GPT 6.1-sol), in collaboration
• Anthropic Claude (Fable 5.1), in collaboration
• ssh-agent-crypt and its contributors
• Code signing, courtesy of Essilor International

ISC license.

Documentation

Overview

Package vauthlogin authenticates to Vault using ssh-agent or JWT and caches the token with ssh-agent-crypt. It does not resolve environments.

Index

• Constants
• Variables
• func CheckProjectVersion(manifest, version string) error
• func Environ() map[string]string
• func HumanDiff(seconds float64, max int) string
• func KnownVault(addr, home string, environ map[string]string) bool
• func LocateRC(environ map[string]string, cwd, home string) string
• func ReplaceEnv(str string, dict Lookup) string
• type HTTPError
  • func (e *HTTPError) Error() string
• type JWTAuth
• type Lookup
• type LookupToken
• type RC
  • func ParseRC(body []byte, file string, environ map[string]string) (*RC, error)
  • func (rc *RC) AuthKey() string
• type SSHAuth
• type Vauth
  • func New() (*Vauth, error)
  • func (v *Vauth) Connect(renew bool) (string, error)
  • func (v *Vauth) LookupSelf(token string) (*LookupToken, error)
  • func (v *Vauth) Request(method, path, token string, payload any, expect int) (int, []byte, error)
  • func (v *Vauth) TokenCacheFile() string
  • func (v *Vauth) TokenCacheKey() string
  • func (v *Vauth) VaultURL(path string) string

Constants

const PackageName = "vauth-login"

PackageName is the npm name a project uses to pin vauth: `"dependencies": {"vauth-login": "^1.0.0"}` in its package.json.

Variables

var Version string

Version is the running version (ldflags -X or debug.ReadBuildInfo), checked by New against the current directory's package.json; empty or non-semver values ("(devel)") skip the check.

Functions

func CheckProjectVersion

func CheckProjectVersion(manifest, version string) error

CheckProjectVersion fails when manifest (a package.json) declares a dependency on PackageName that version does not satisfy. A missing manifest, dependency or unparseable version is not an error.

func Environ

func Environ() map[string]string

Environ converts os.Environ() into a map.

func HumanDiff

func HumanDiff(seconds float64, max int) string

HumanDiff formats a duration in seconds with at most max units ("1d 3h"), like nyks/date/humanDiff.

func KnownVault

func KnownVault(addr, home string, environ map[string]string) bool

KnownVault reports whether addr is the vault_addr or one of the known_vaults of the user's ~/.vauthrc at home, or the environment's VAULT_ADDR. The environment is trusted even without a readable home file.

func LocateRC

func LocateRC(environ map[string]string, cwd, home string) string

LocateRC returns the first existing configuration file among VAUTHRC, ./.vauthrc and ~/.vauthrc, or an empty string.

func ReplaceEnv

func ReplaceEnv(str string, dict Lookup) string

ReplaceEnv expands $$key and $${key} macros against dict (nyks string/replaceEnv semantics): unknown keys stay, expansions recurse.

Types

type HTTPError

type HTTPError struct {
	Status int
	Body   string
}

HTTPError reports an unexpected Vault status code.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type JWTAuth

type JWTAuth struct {
	Path string `yaml:"path"`
	JWT  string `yaml:"jwt"`
	Role string `yaml:"role"`
}

JWTAuth configures a Vault jwt login.

type Lookup

type Lookup map[string]any

Lookup resolves dotted paths ($${env.X}) in nested string maps.

type LookupToken

type LookupToken struct {
	TTL           float64 `json:"ttl"`
	Renewable     bool    `json:"renewable"`
	CreationTTL   int64   `json:"creation_ttl"`
	EntityID      string  `json:"entity_id"`
	LeaseDuration int64   `json:"lease_duration"`
}

LookupToken is the token metadata returned by lookup-self.

type RC

type RC struct {
	VaultAddr  string   `yaml:"vault_addr"`
	SSHAuth    *SSHAuth `yaml:"ssh_auth"`
	JWTAuth    *JWTAuth `yaml:"jwt_auth"`
	TokenCache *bool    `yaml:"token_cache"`
	// KnownVaults lists, in ~/.vauthrc, the Vault addresses a project's
	// ./.vauthrc is allowed to select.
	KnownVaults []string `yaml:"known_vaults"`
	// contains filtered or unexported fields
}

RC is the parsed .vauthrc, after $${env.X} expansion.

func ParseRC

func ParseRC(body []byte, file string, environ map[string]string) (*RC, error)

ParseRC parses a .vauthrc body and expands its $${env.X} macros against environ. All other configuration sections are ignored.

func (*RC) AuthKey

func (rc *RC) AuthKey() string

AuthKey renders ssh_auth and jwt_auth as JSON members, in the order of the parsed document. Programmatic configurations are rendered from the structs.

type SSHAuth

type SSHAuth struct {
	Path string `yaml:"path"`
	Role string `yaml:"role"`
}

SSHAuth configures the Vault ssh auth plugin (nonce challenge).

type Vauth

type Vauth struct {
	RC         RC
	VaultAddr  string
	VaultToken string
	// Agent is the ssh-agent address; empty disables ssh authentication.
	Agent string
	// TokenCache enables the on-disk token cache in CacheDir.
	TokenCache bool
	CacheDir   string
	HomeDir    string
	// Environ is the process environment snapshot used for macros.
	Environ map[string]string
	// Stderr defaults to the process error stream.
	Stderr     io.Writer
	HTTPClient *http.Client
	// Now overrides the clock (tests).
	Now func() time.Time
	// RCFile is the configuration file New selected, if any.
	RCFile string
	// contains filtered or unexported fields
}

Vauth is a configured client. New builds one from the process environment; fields may be set directly for programmatic use.

func New

func New() (*Vauth, error)

New loads the configuration from the environment and the first .vauthrc found (VAUTHRC, ./.vauthrc, ~/.vauthrc).

func (*Vauth) Connect

func (v *Vauth) Connect(renew bool) (string, error)

Connect establishes VaultToken: an inherited token is returned as is; otherwise the cached one (renewed in the last third of its lease), then a new login. With renew, a new login is forced. Without an authentication method, no token is used.

func (*Vauth) LookupSelf

func (v *Vauth) LookupSelf(token string) (*LookupToken, error)

LookupSelf validates a token online and returns metadata including entity ID.

func (*Vauth) Request

func (v *Vauth) Request(method, path, token string, payload any, expect int) (int, []byte, error)

Request performs a JSON Vault call. Set expect to zero to handle status yourself.

func (*Vauth) TokenCacheFile

func (v *Vauth) TokenCacheFile() string

TokenCacheFile is the armored cache file for this configuration.

func (*Vauth) TokenCacheKey

func (v *Vauth) TokenCacheKey() string

TokenCacheKey isolates cached tokens by Vault address and authentication configuration. It matches the Node implementation byte for byte.

func (*Vauth) VaultURL

func (v *Vauth) VaultURL(path string) string

VaultURL returns an API URL relative to this configured Vault.