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. The CLI writes a final newline to stderr after the token so the terminal prompt starts on its own line.

Force a fresh login:

vauth-login --renew

In CI, supply the trusted Vault address through the environment. Only a matching project address passes the trust check 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 project-selected Vault must match VAULT_ADDR, the vault_addr in ~/.vauthrc, or one of its known_vaults. Explicit VAUTHRC and home configuration are trusted operator inputs.

# ~/.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.

Tokens and caching

VAULT_TOKEN takes precedence: it is returned unchanged, without contacting Vault or writing it to the cache. Otherwise, vauth-login reuses a cached token or authenticates with the configured SSH/JWT method. --renew skips reuse and forces fresh authentication.

In the last third of a cached token's lease, vauth-login renews it if renewable or logs in again if not. Expired tokens and renewals rejected with 400/403 also trigger login. Network and server errors remain errors, not a reason to silently reauthenticate.

The cache lives at ~/.vauth/tokens/<session-sha256>.creds, encrypted and authenticated by ssh-agent-crypt. Node and Go share its format; each runtime uses its own home directory. Set token_cache: false to disable it. A cache-write failure does not prevent returning the token.

Encryption selects VAUTH_USER_IDENTITY, then VAUTH_USER_MAIL, then the ssh-agent-crypt default selector. Decryption uses the key fingerprint stored in the cache.

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.

The prototype client API is Connect, LookupSelf, Request in Node and Go. Read-only RC, VAULT_ADDR and VAULT_TOKEN readers expose the complete parsed configuration, effective address and current token. The file path and authentication state remain internal; embedding code can read the document without reopening its file. Old Node method spellings and exported cache/URL helpers are removed, without compatibility aliases; update SDK callers accordingly. The standalone CLI contract remains unchanged.

Security audit

Two fresh independent source assessments cover the published 1.1.4 release: SECURITY_AUDIT_fable-5.1.md and SECURITY_AUDIT_gpt-6.1-sol.md.

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

Both were generated on October 25, 2026 from clean release commit b80d311 (tag v1.1.4), after publication, as requested. These reports are published on the repository's main branch, not retroactively inserted into the release tag or npm tarball of 1.1.4; that tagged README retains the earlier 1.1.3 assessments. Subsequent Node 16 compatibility updates are outside that assessed commit.

The host confirmed models claude-fable-5-1 and gpt-6.1-sol_codeassist, exact inputs, source immutability and read exclusions. Claude prepared the Sol stdin; each reviewer independently examined current source without the other report, prior assessments, scores, task handoffs or README content. Both raw reports are preserved after separate host-provenance blocks; their findings and scores are not rewritten for agreement.

Sol ran syntax/format checks and bounded offline probes; it did not execute full suites, Go vet or ESLint. Fable ran ESLint, formatting and offline Go vet plus synthetic macro probes, using temporary compiler files. Its Node/Go suite attempts were blocked by sandbox socket binding, not product regressions or successful suite execution. Local installed dependency sources and an ignored lockfile were support inputs, not a committed release lockfile. Each report's host provenance separates these limits from the raw reviewer observations.

Separate host validation passes 85 Node tests on Node 24, ESLint, Go vet/race and Linux/Windows compilation. Publication validation confirms all three CI workflows succeeded, npm latest and tarball integrity/source, Go proxy source, GitHub binary checksums, Linux CLI version/help and Windows Authenticode signature. These are host checks, not tests attributed to the reviewers.

The assessments are source-only reviews, not certification or live vulnerability-database clearance. Review each report's evidence, hypotheses and check-scope limitations before interpreting its scores.

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 KnownVault(addr, home string, environ map[string]string) bool
• func LocateRC(environ map[string]string, cwd, home string) string
• type HTTPError
  • func (e *HTTPError) Error() string
• type JWTAuth
• 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) RC() map[string]any
  • func (v *Vauth) Request(method, path, token string, payload any, expect int) (int, []byte, error)
  • func (v *Vauth) VAULT_ADDR() string
  • func (v *Vauth) VAULT_TOKEN() 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 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.

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 `json:"path" yaml:"path"`
	JWT  string `json:"jwt" yaml:"jwt"`
	Role string `json:"role" yaml:"role"`
}

JWTAuth configures a Vault jwt login.

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   `json:"vault_addr" yaml:"vault_addr"`
	SSHAuth    *SSHAuth `json:"ssh_auth" yaml:"ssh_auth"`
	JWTAuth    *JWTAuth `json:"jwt_auth" yaml:"jwt_auth"`
	TokenCache *bool    `json:"token_cache" yaml:"token_cache"`
	// KnownVaults lists, in ~/.vauthrc, the Vault addresses a project's
	// ./.vauthrc is allowed to select.
	KnownVaults []string `json:"known_vaults" yaml:"known_vaults"`
	// contains filtered or unexported fields
}

RC is the private authentication view, with the complete JSON snapshot retained.

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 for the private authentication view; the complete JSON document is retained.

func (*RC) AuthKey

func (rc *RC) AuthKey() string

AuthKey composes explicit authentication fields; document order is irrelevant.

type SSHAuth

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

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

type Vauth

type Vauth struct {

	// 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
	// contains filtered or unexported fields
}

Vauth is a configured client. New builds one from the process environment; authentication data and the selected file path are private.

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) RC

func (v *Vauth) RC() map[string]any

RC returns an independent snapshot of the complete parsed document.

func (*Vauth) Request

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

Request performs a Vault API call after checking destination trust. A JSON payload is sent when non-nil. With expect > 0, another status is returned as *HTTPError.

func (*Vauth) VAULT_ADDR

func (v *Vauth) VAULT_ADDR() string

VAULT_ADDR returns the effective address, including the environment fallback.

func (*Vauth) VAULT_TOKEN

func (v *Vauth) VAULT_TOKEN() string

VAULT_TOKEN returns the current token; Connect owns changes to it.