vvauth 2.4.1 → 2.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/publish-npm.yml +5 -0
- package/.github/workflows/release.yml +33 -0
- package/.github/workflows/test.yml +52 -0
- package/.goreleaser.yaml +31 -0
- package/API_and_tests.md +144 -0
- package/README.md +88 -17
- package/SECURITY_AUDIT_fable-5.1.md +88 -0
- package/SECURITY_AUDIT_gpt-6.1-sol.md +196 -0
- package/cmd/vauth/main.go +218 -0
- package/go.mod +18 -0
- package/go.sum +24 -0
- package/index.js +146 -345
- package/package.json +7 -7
- package/rc.go +320 -0
- package/test/token-cache.js +271 -135
- package/vault.go +46 -0
- package/vauth.go +399 -0
- package/vauth_test.go +868 -0
|
@@ -17,7 +17,12 @@ jobs:
|
|
|
17
17
|
with:
|
|
18
18
|
node-version: '24.x'
|
|
19
19
|
registry-url: 'https://registry.npmjs.org'
|
|
20
|
+
- uses: actions/setup-go@v5
|
|
21
|
+
with:
|
|
22
|
+
go-version-file: go.mod
|
|
20
23
|
- run: npm install
|
|
21
24
|
- run: npm run eslint
|
|
22
25
|
- run: npm test
|
|
26
|
+
- run: go vet ./...
|
|
27
|
+
- run: go test ./...
|
|
23
28
|
- run: npm publish
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
name: release
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
tags:
|
|
5
|
+
- 'v*'
|
|
6
|
+
|
|
7
|
+
permissions:
|
|
8
|
+
contents: write
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
goreleaser:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
environment: production
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
with:
|
|
17
|
+
fetch-depth: 0
|
|
18
|
+
- uses: actions/setup-go@v5
|
|
19
|
+
with:
|
|
20
|
+
go-version-file: go.mod
|
|
21
|
+
- run: go vet ./... && go test ./...
|
|
22
|
+
- uses: actions/checkout@v4
|
|
23
|
+
with:
|
|
24
|
+
repository: 131/gh-actions
|
|
25
|
+
ref: v1
|
|
26
|
+
path: .gh-actions
|
|
27
|
+
- uses: goreleaser/goreleaser-action@v6
|
|
28
|
+
with:
|
|
29
|
+
version: '~> v2'
|
|
30
|
+
args: release --clean
|
|
31
|
+
env:
|
|
32
|
+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
33
|
+
SIGNING_SERVER: ${{ secrets.SIGNING_SERVER }}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
name: test
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
branches: ['**']
|
|
5
|
+
pull_request:
|
|
6
|
+
|
|
7
|
+
permissions:
|
|
8
|
+
contents: read
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
node:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
- uses: actions/setup-node@v4
|
|
16
|
+
with:
|
|
17
|
+
node-version: '24.x'
|
|
18
|
+
- run: npm install
|
|
19
|
+
- run: npm run eslint
|
|
20
|
+
- run: npm test
|
|
21
|
+
|
|
22
|
+
go:
|
|
23
|
+
strategy:
|
|
24
|
+
matrix:
|
|
25
|
+
os: [ubuntu-latest, windows-latest]
|
|
26
|
+
runs-on: ${{ matrix.os }}
|
|
27
|
+
steps:
|
|
28
|
+
# Windows runners ship Git with core.autocrlf=true, which would turn LF sources into CRLF
|
|
29
|
+
- run: git config --global core.autocrlf false
|
|
30
|
+
- uses: actions/checkout@v4
|
|
31
|
+
- uses: actions/setup-go@v5
|
|
32
|
+
with:
|
|
33
|
+
go-version-file: go.mod
|
|
34
|
+
- run: gofmt -l . && test -z "$(gofmt -l .)"
|
|
35
|
+
shell: bash
|
|
36
|
+
- run: go vet ./...
|
|
37
|
+
- run: go test ./...
|
|
38
|
+
if: runner.os == 'Linux'
|
|
39
|
+
- run: go build ./cmd/vauth
|
|
40
|
+
if: runner.os == 'Windows'
|
|
41
|
+
|
|
42
|
+
runtime-node16:
|
|
43
|
+
runs-on: ubuntu-latest
|
|
44
|
+
steps:
|
|
45
|
+
- uses: actions/checkout@v4
|
|
46
|
+
- uses: actions/setup-node@v4
|
|
47
|
+
with:
|
|
48
|
+
node-version: '16.x'
|
|
49
|
+
- run: npm install --omit=dev --ignore-scripts --no-audit
|
|
50
|
+
- run: |
|
|
51
|
+
node --check index.js
|
|
52
|
+
node index.js version
|
package/.goreleaser.yaml
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
version: 2
|
|
2
|
+
|
|
3
|
+
project_name: vauth
|
|
4
|
+
|
|
5
|
+
builds:
|
|
6
|
+
- id: linux
|
|
7
|
+
main: ./cmd/vauth
|
|
8
|
+
goos: [linux]
|
|
9
|
+
goarch: [amd64]
|
|
10
|
+
flags: [-trimpath]
|
|
11
|
+
ldflags: ['-s -w -X main.version={{ .Tag }}']
|
|
12
|
+
- id: windows
|
|
13
|
+
main: ./cmd/vauth
|
|
14
|
+
goos: [windows]
|
|
15
|
+
goarch: [amd64]
|
|
16
|
+
flags: [-trimpath]
|
|
17
|
+
ldflags: ['-s -w -X main.version={{ .Tag }}']
|
|
18
|
+
hooks:
|
|
19
|
+
post: .gh-actions/sign-binaries/sign {{ .Path }}
|
|
20
|
+
|
|
21
|
+
archives:
|
|
22
|
+
- formats: [binary]
|
|
23
|
+
name_template: '{{ .ProjectName }}-{{ .Os }}-{{ .Arch }}'
|
|
24
|
+
|
|
25
|
+
checksum:
|
|
26
|
+
name_template: SHA256SUMS
|
|
27
|
+
|
|
28
|
+
changelog:
|
|
29
|
+
filters:
|
|
30
|
+
exclude:
|
|
31
|
+
- '^v[0-9]+\.[0-9]+\.[0-9]+$'
|
package/API_and_tests.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# vvauth: CLI contract, API and tests
|
|
2
|
+
|
|
3
|
+
Back to the [README](README.md). Node (`npm install -g vvauth`) and Go
|
|
4
|
+
(`go install github.com/131/vvauth/v2/cmd/vauth@latest`, release binaries)
|
|
5
|
+
expose the same `vauth` command; everything below holds for both.
|
|
6
|
+
|
|
7
|
+
## CLI contract
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
vauth <command> [positional...] [--flag[=value]] [--ir://json]
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`env.map` names must match `^[A-Za-z_][A-Za-z0-9_]*$`; any other key is an
|
|
14
|
+
error, since names reach `export KEY=` unescaped. Flags may replace positionals (`vauth set GITLAB_TOKEN x` ≡
|
|
15
|
+
`vauth set --k=GITLAB_TOKEN --v=x`). `--flag` alone means `true`; `--flag=`,
|
|
16
|
+
`--flag=false` and `--flag=0` mean `false`. `--` ends flag parsing.
|
|
17
|
+
|
|
18
|
+
| Command | Effect | stdout |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| `env [--source] [--renew]` | Resolve the `.vauthrc` environment (`env.map`, `env.paths`, `env.git`, `ssh-agent-crypt`) | JSON object with `--ir://json`; `export K='v'` lines with `--source`; JSON otherwise |
|
|
21
|
+
| `login [--source] [--renew]` | Authenticate, cache the token | `export VAULT_TOKEN='…'` with `--source`; nothing otherwise |
|
|
22
|
+
| `connect [--renew]` | Authenticate, print the token | raw token, no trailing newline (`--ir://json`: JSON string) |
|
|
23
|
+
| `run <command> [args...]` | Run a command with the resolved environment merged over the current one | the command's; exit code propagated |
|
|
24
|
+
| `dotenv` | Resolved environment as `K=v` lines | one `K=v` per line |
|
|
25
|
+
| `show` | Identity metadata merged over `.vauth_database` | JSON object |
|
|
26
|
+
| `set <key> <value>` | Store `KEY` (upper-cased) in `private/<login>/.vauth_database` | nothing |
|
|
27
|
+
| `unset <key>` | Remove a key from `.vauth_database` | nothing |
|
|
28
|
+
| `install` | Append the `venv` shell function to `~/.bashrc` | nothing |
|
|
29
|
+
| `version` (`--version`) | Build version | one line |
|
|
30
|
+
|
|
31
|
+
Diagnostics (`Vauth token: generated · 12h`, `export K=[redacted]`,
|
|
32
|
+
errors) go to stderr; stdout is machine-readable for every command. Exit code is
|
|
33
|
+
`0` on success, `1` on error (or the child's code for `run`). `--renew` discards
|
|
34
|
+
the cached token and authenticates again.
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
vauth env --ir://json # {"VAULT_TOKEN":"…","VAULT_ADDR":"…","TF_HTTP_USERNAME":"…"}
|
|
38
|
+
source <(vauth env --source) # what the `venv` function does
|
|
39
|
+
vauth run -- terraform plan
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Environment
|
|
43
|
+
|
|
44
|
+
| Variable | Role |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `VAUTHRC` | Explicit `.vauthrc` path; else `./.vauthrc`, then `~/.vauthrc` |
|
|
47
|
+
| `VAULT_ADDR` | Fallback when `.vauthrc` has no `vault_addr` |
|
|
48
|
+
| `VAULT_TOKEN` | Returned offline by Connect without renewal/persistence; LookupSelf validates online when the profile is requested |
|
|
49
|
+
| `SSH_AUTH_SOCK` | Agent for `ssh_auth` and for the token cache; on Windows, else Pageant (≥ 0.75), else the OpenSSH pipe |
|
|
50
|
+
| `VAUTH_USER_IDENTITY`, `VAUTH_USER_MAIL` | Agent key selector for the token cache (first key otherwise) |
|
|
51
|
+
| `CI` | When set, `env.gitlab` does not derive `CI_PROJECT_*` from `git remote get-url origin` |
|
|
52
|
+
|
|
53
|
+
Tokens are cached in `~/.vauth/tokens/<sha256(vault_addr, ssh_auth, jwt_auth)>.creds`,
|
|
54
|
+
armored with [ssh-agent-crypt](https://github.com/131/ssh-agent-crypt);
|
|
55
|
+
`token_cache: false` disables the cache. Without an agent, nothing is written.
|
|
56
|
+
|
|
57
|
+
## Node module
|
|
58
|
+
|
|
59
|
+
Node.js 16 or newer is supported. CI checks JavaScript syntax and CLI/module
|
|
60
|
+
loading on Node 16 separately from the existing suite. JSON copies use
|
|
61
|
+
`nyks/object/structuredClone`, native when available with a JSON fallback.
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
const Vauth = require('vvauth');
|
|
65
|
+
const vauth = new Vauth(); // reads .vauthrc and process.env
|
|
66
|
+
const token = await vauth.Connect(); // Connect(renew = false)
|
|
67
|
+
const env = await vauth.Env(); // Env(source = false, renew = false) → object
|
|
68
|
+
await vauth.Login(false, true); // login(source, renew)
|
|
69
|
+
const profile = await vauth.Show(); // {...database, ...metadata}
|
|
70
|
+
await vauth.Set('KEY', 'value'); await vauth.Unset('KEY');
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Node extends the vauth-login client directly. `Connect`, `LookupSelf` and
|
|
74
|
+
`Request` are inherited, not forwarded through compatibility wrappers.
|
|
75
|
+
`GetProfile`, `Env`, `Show`, `Set`, `Unset`, `Login`, `Dotenv`, `Run` and
|
|
76
|
+
`PublishEnv` own the environment/profile behavior. `Version()` is static.
|
|
77
|
+
`RC`, `VAULT_ADDR` and `VAULT_TOKEN` are the inherited read-only getters.
|
|
78
|
+
`config` contains a mutable copy of only `env` and `ssh-agent-crypt`, with local
|
|
79
|
+
`env` macros expanded; the full frozen RC retains original values/macros.
|
|
80
|
+
vvauth does not reopen the selected configuration file.
|
|
81
|
+
|
|
82
|
+
`Env(true)`, `Login(true)`, `Dotenv()` and `PublishEnv()` write to stdout but do
|
|
83
|
+
not exit the SDK caller. `Run(command, ...args)` returns the child's exit code;
|
|
84
|
+
launch/authentication errors reject. Public methods use PascalCase without old
|
|
85
|
+
SDK aliases. The CLI independently keeps its lowercase commands and flags,
|
|
86
|
+
without reflecting inherited HTTP methods into CLI commands.
|
|
87
|
+
|
|
88
|
+
## Go module
|
|
89
|
+
|
|
90
|
+
```go
|
|
91
|
+
import vvauth "github.com/131/vvauth/v2"
|
|
92
|
+
|
|
93
|
+
v, err := vvauth.New() // .vauthrc + os.Environ()
|
|
94
|
+
token, err := v.Connect(false) // renew bool
|
|
95
|
+
env, err := v.Env(false) // *OrderedMap, deterministic output order
|
|
96
|
+
profile, err := v.GetProfile(false) // EntityID, Metadata, Database; Merged()
|
|
97
|
+
err = v.Login(source, renew)
|
|
98
|
+
err = v.Set("KEY", "value"); err = v.Unset("KEY")
|
|
99
|
+
code, err := v.Run("terraform", "plan")
|
|
100
|
+
v.PublishEnv(env) // export lines on stdout, redacted echo on stderr
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`Vauth` embeds `*vauthlogin.Vauth`; `Connect`, `LookupSelf` and `Request`,
|
|
104
|
+
the read-only `RC()`, `VAULT_ADDR()` and `VAULT_TOKEN()` readers, plus mutable
|
|
105
|
+
`Agent`, `TokenCache`, `CacheDir`, `HomeDir`, `Environ`, `Stderr`, `Now` and
|
|
106
|
+
`HTTPClient` settings, are owned by that client.
|
|
107
|
+
Use `New()` or supply the embedded client explicitly for isolated programmatic
|
|
108
|
+
use. `Config` holds only `Env`/`AgentCrypt`; `Stdout`/`Stdin` belong to vvauth.
|
|
109
|
+
`ParseConfig`, `ReplaceEnv`, `ShellEscape` and `FunctionExists` support environment and shell operations.
|
|
110
|
+
Construction consumes `RC()` directly: an independent JSON snapshot is decoded
|
|
111
|
+
into vvauth's own configuration, without reopening its file. The JSON map does
|
|
112
|
+
not retain YAML key order; `env.map` keys from this path have deterministic sorted
|
|
113
|
+
order. Explicit `OrderedMap.Set` calls and standalone `ParseConfig` keep their
|
|
114
|
+
insertion/YAML order. There is no second auth parser, token lifecycle, cache
|
|
115
|
+
implementation or HTTP transport in vvauth.
|
|
116
|
+
|
|
117
|
+
Node and Go consume vauth-login 1.1.5 and ssh-agent-crypt 1.4.2; Node uses nyks
|
|
118
|
+
6.17.0. `env.gitlab` derives `CI_PROJECT_*` from the current working repository,
|
|
119
|
+
including when `VAUTHRC` is elsewhere. In CI, supplied variables are retained.
|
|
120
|
+
This is distinct from standalone Go `ParseConfig`, whose explicit file argument
|
|
121
|
+
identifies its Git directory.
|
|
122
|
+
|
|
123
|
+
The SDK keeps language-native conventions: promises/throws in Node,
|
|
124
|
+
values plus errors in Go. Node `Env(source, renew)` can publish directly;
|
|
125
|
+
Go `Env(renew)` returns an ordered map for `PublishEnv`. CLI `--ir://json`
|
|
126
|
+
outputs JSON without a trailing newline in both implementations. JSON object
|
|
127
|
+
key order is not part of the profile (`show`) contract.
|
|
128
|
+
|
|
129
|
+
## Tests
|
|
130
|
+
|
|
131
|
+
Node and Go are tested against an in-process fake Vault (nonce, login, lookup,
|
|
132
|
+
renew, identity, KV) and a throwaway `ssh-agent`; both suites cover token reuse,
|
|
133
|
+
renewal in the final third, expiry, isolation of the cache by Vault and auth,
|
|
134
|
+
corrupt or plaintext cache rejection, identity selection and the interoperability
|
|
135
|
+
of the armored cache with the `ssh-agent-crypt` CLI.
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
npm install && npm run eslint && npm test
|
|
139
|
+
gofmt -l . && go vet ./... && go test ./...
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
CI (`test.yml`) runs both on Linux and Windows runners; `release.yml` builds the
|
|
143
|
+
static binaries on `v*` tags, signs the Windows one when `SIGNING_SERVER` is
|
|
144
|
+
set, and attaches `SHA256SUMS`.
|
package/README.md
CHANGED
|
@@ -1,8 +1,53 @@
|
|
|
1
|
-
|
|
1
|
+
# vvauth
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Node.js 16 or newer is supported; CI includes Node 16 JavaScript syntax and
|
|
4
|
+
module/CLI loading checks alongside the existing test suites.
|
|
5
|
+
|
|
6
|
+
Resolve a shell environment from your Vault identity, private settings and
|
|
7
|
+
secrets. [vauth-login](https://github.com/131/vauth-login) handles authentication,
|
|
8
|
+
token caching and HTTP; vvauth owns profiles, macro expansion, KV operations
|
|
9
|
+
and environment publication. Available as a Node module/CLI and a Go module/CLI.
|
|
10
|
+
Both consume vauth-login 1.1.5's complete read-only RC and token/address readers;
|
|
11
|
+
vvauth copies its own sections for macro expansion without reopening the file.
|
|
12
|
+
|
|
13
|
+
# Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# node
|
|
17
|
+
npm install -g vvauth
|
|
18
|
+
|
|
19
|
+
# go
|
|
20
|
+
go install github.com/131/vvauth/v2/cmd/vauth@latest
|
|
21
|
+
|
|
22
|
+
# static binary, linux
|
|
23
|
+
wget -O vauth https://github.com/131/vvauth/releases/latest/download/vauth-linux-amd64
|
|
24
|
+
chmod +x vauth
|
|
25
|
+
|
|
26
|
+
# static binary, windows (curl.exe ships with every supported Windows, cmd or PowerShell)
|
|
27
|
+
curl.exe -fsSL -o vauth.exe https://github.com/131/vvauth/releases/latest/download/vauth-windows-amd64.exe
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The [npm](https://www.npmjs.com/package/vvauth) module and the Go module ship
|
|
31
|
+
the same `vauth` command, flags and `.vauthrc`, and share the token cache.
|
|
32
|
+
Binaries are static, signed on Windows, with `SHA256SUMS` on every
|
|
33
|
+
[release](https://github.com/131/vvauth/releases); `vauth version` prints the
|
|
34
|
+
build version. On Windows, the SSH agent is `SSH_AUTH_SOCK` when set, else
|
|
35
|
+
Pageant (≥ 0.75, named pipe autodiscovery), else the OpenSSH agent pipe.
|
|
36
|
+
|
|
37
|
+
## The `venv` shell function
|
|
38
|
+
|
|
39
|
+
A program cannot change the environment of the shell that started it, so the
|
|
40
|
+
`VAULT_TOKEN`, credentials and `env.map` variables that `vauth` resolves have
|
|
41
|
+
to be *sourced*. `vauth install` appends this one-liner to `~/.bashrc`:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
function venv() { source <(/usr/bin/env vauth env --source "$@"); }
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`venv` then loads the resolved environment into the current shell (`venv
|
|
48
|
+
--renew` forces a fresh token); the exported names are echoed to stderr with
|
|
49
|
+
their values redacted. In scripts or CI, without a shell to source into, use
|
|
50
|
+
`vauth run <command>`, `vauth env --ir://json` or `vauth dotenv` instead.
|
|
6
51
|
|
|
7
52
|
|
|
8
53
|
# Vauth configuration
|
|
@@ -26,7 +71,7 @@ The configuration file should abide the following schema
|
|
|
26
71
|
# vauth URL
|
|
27
72
|
vault_addr: https://vauth.myserver.org
|
|
28
73
|
|
|
29
|
-
#
|
|
74
|
+
# SSH authentication role, consumed by vauth-login
|
|
30
75
|
ssh_auth:
|
|
31
76
|
role: $${env.VAUTH_USER_LOGIN}
|
|
32
77
|
env:
|
|
@@ -46,15 +91,13 @@ env:
|
|
|
46
91
|
```
|
|
47
92
|
|
|
48
93
|
|
|
49
|
-
# Credits
|
|
50
|
-
* [Francois Leurent](https://github.com/131)
|
|
51
|
-
|
|
52
|
-
|
|
53
94
|
# Machine-readable environment
|
|
54
95
|
|
|
55
|
-
`vauth env --ir://json`
|
|
56
|
-
|
|
57
|
-
|
|
96
|
+
`vauth env --ir://json` writes the resolved environment as one JSON object on
|
|
97
|
+
stdout; diagnostics stay on stderr, so a caller can parse stdout directly.
|
|
98
|
+
CLI command spelling remains lowercase; public Node/Go SDK methods use the
|
|
99
|
+
same PascalCase names. Every command, flag, output and module signature is in
|
|
100
|
+
[API_and_tests.md](API_and_tests.md).
|
|
58
101
|
|
|
59
102
|
```bash
|
|
60
103
|
vauth env --ir://json
|
|
@@ -63,15 +106,43 @@ vauth env --ir://json
|
|
|
63
106
|
|
|
64
107
|
# Token cache
|
|
65
108
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
109
|
+
[vauth-login](https://github.com/131/vauth-login) owns the cache in
|
|
110
|
+
`~/.vauth/tokens/<session>.creds`, shared by Node and Go. It reuses, renews or
|
|
111
|
+
replaces cached tokens as needed. An inherited `VAULT_TOKEN` is returned as is,
|
|
112
|
+
without renewal or persistence; profile retrieval is an explicit separate step.
|
|
69
113
|
|
|
70
|
-
Each session file is armored using
|
|
71
|
-
|
|
114
|
+
Each session file is armored using
|
|
115
|
+
[ssh-agent-crypt](https://github.com/131/ssh-agent-crypt) and your SSH agent’s
|
|
116
|
+
first key (`VAUTH_USER_IDENTITY`, then `VAUTH_USER_MAIL`, select another one).
|
|
117
|
+
Without an SSH agent, disk caching is disabled.
|
|
72
118
|
|
|
73
119
|
Set `token_cache: false` in `.vauthrc` to disable disk cache reads and writes.
|
|
74
120
|
|
|
75
121
|
## Force reauthentication
|
|
76
122
|
|
|
77
123
|
`venv --renew` forces authentication, generates and caches a new token.
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
## Security audit
|
|
127
|
+
|
|
128
|
+
The reports below describe the pre-integration implementation. This integration
|
|
129
|
+
uses vauth-login 1.1.5 without regenerating or rewriting their findings/scores.
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
Two independent reviews of the design and of both implementations (Node, Go),
|
|
133
|
+
each scoring Coolness, Robustness and Safety out of 20:
|
|
134
|
+
[SECURITY_AUDIT_fable-5.1.md](SECURITY_AUDIT_fable-5.1.md) and
|
|
135
|
+
[SECURITY_AUDIT_gpt-6.1-sol.md](SECURITY_AUDIT_gpt-6.1-sol.md).
|
|
136
|
+
|
|
137
|
+
| Criterion | Codex (Claude Fable 5.1) | Codex (GPT 6.1) |
|
|
138
|
+
| --- | ---: | ---: |
|
|
139
|
+
| ✨ **Coolness** | 15/20 | 17/20 |
|
|
140
|
+
| Robustness | 16/20 | 11/20 |
|
|
141
|
+
| Safety | 14/20 | 10/20 |
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
# Credits
|
|
145
|
+
* [Francois Leurent](https://github.com/131)
|
|
146
|
+
* [OpenAI](https://openai.com) Codex (GPT 6.1-sol), in collaboration
|
|
147
|
+
* [Anthropic](https://www.anthropic.com) Claude (Fable 5.1), in collaboration
|
|
148
|
+
* Code signing, courtesy of Essilor International
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# vvauth: design review by Codex (Claude Fable 5.1)
|
|
2
|
+
|
|
3
|
+
Independent review of the design and of the Node and Go implementations of
|
|
4
|
+
[vvauth](README.md), scoring Coolness, Robustness and Safety out of 20. The
|
|
5
|
+
companion review is [SECURITY_AUDIT_gpt-6.1-sol.md](SECURITY_AUDIT_gpt-6.1-sol.md).
|
|
6
|
+
|
|
7
|
+
## The design, as read
|
|
8
|
+
|
|
9
|
+
`vauth` turns a `.vauthrc` (YAML with `$${env.X}`, `$${profile.X}`,
|
|
10
|
+
`$${secrets.X}` macros) into a Vault token and a resolved environment. Two
|
|
11
|
+
authentication flows: `jwt_auth` (CI) and `ssh_auth`, where the agent signs a
|
|
12
|
+
nonce fetched from `auth/<path>/nonce`, so the user's SSH key is the identity
|
|
13
|
+
and nothing else is stored. The token is cached in
|
|
14
|
+
`~/.vauth/tokens/<sha256(vault_addr, ssh_auth, jwt_auth)>.creds`, armored with
|
|
15
|
+
ssh-agent-crypt (key derived from an agent signature), reused while valid,
|
|
16
|
+
renewed in the last third of its lease, replaced when expired or rejected.
|
|
17
|
+
`env --source` prints `export K='v'` lines for the `venv` shell function;
|
|
18
|
+
`--ir://json` prints one JSON object for automation. Node and Go share the
|
|
19
|
+
contract byte for byte (cache key, armor, outputs) and are cross-tested.
|
|
20
|
+
|
|
21
|
+
## Strengths
|
|
22
|
+
|
|
23
|
+
- No long-lived secret on disk besides a Vault token that is itself encrypted
|
|
24
|
+
under the agent, with `0700`/`0600` modes, write-to-temp-then-rename, and a
|
|
25
|
+
cache that degrades to "not persisted" rather than "stored in clear".
|
|
26
|
+
- Correct lease handling: renewal only in the final third, `lookup-self` TTL
|
|
27
|
+
trusted over the local clock when the token is foreign, reauthentication only
|
|
28
|
+
on `400`/`403`, never on network failures (no accidental token storm).
|
|
29
|
+
- Secret values never reach stdout unescaped in `--source` mode
|
|
30
|
+
(`ShellEscape` single-quotes), `env.map` names are checked against
|
|
31
|
+
`^[A-Za-z_][A-Za-z0-9_]*$` before they reach `export`, and the shell echoes
|
|
32
|
+
`[redacted]`.
|
|
33
|
+
- The nonce is fetched fresh for every key tried; the agent only ever signs
|
|
34
|
+
server-provided data, no private key is handled by the tool.
|
|
35
|
+
- Two implementations with the same fake-Vault test matrix catch divergence;
|
|
36
|
+
the Go binary is static, signed, with `SHA256SUMS`; release runs the tests.
|
|
37
|
+
|
|
38
|
+
## Weaknesses and remedies
|
|
39
|
+
|
|
40
|
+
1. **`vault_addr` from the current directory redirects authentication.** A
|
|
41
|
+
hostile `.vauthrc` points to an attacker-controlled "Vault"; the tool then
|
|
42
|
+
fetches a nonce from it and has the agent sign it. The signature is over
|
|
43
|
+
attacker-chosen bytes (bounded to valid UTF-8 by the JSON transport, which
|
|
44
|
+
keeps it away from SSHSIG and SSH-userauth encodings, so no direct
|
|
45
|
+
cross-protocol reuse today), and the public key and role name are sent to
|
|
46
|
+
the attacker. *Remedy:* wrap the nonce in a vauth-specific preamble before
|
|
47
|
+
signing (as SSHSIG does), or require `https` plus a pinned allow-list of
|
|
48
|
+
Vault hosts in `~/.vauthrc`; at least surface the Vault address in the
|
|
49
|
+
`Vauth token:` status line on first contact. More generally, a
|
|
50
|
+
`./.vauthrc` from a cloned repository is trusted for everything; a cleaner
|
|
51
|
+
model would let it carry only the project part (`env.map`, `env.paths`,
|
|
52
|
+
`env.gitlab`) and keep `vault_addr`, `ssh_auth`, `jwt_auth` and
|
|
53
|
+
`ssh-agent-crypt` to `~/.vauthrc` or `VAUTHRC`.
|
|
54
|
+
2. **Whoever reaches the agent socket reads the token cache.** By design of
|
|
55
|
+
ssh-agent-crypt; nothing in vvauth adds a second factor. *Remedy:* document
|
|
56
|
+
it next to `token_cache` and recommend `ssh-add -c` on the cache key
|
|
57
|
+
(`SSH_AGENT_CRYPT_KEY` lets a dedicated, confirmed key be chosen).
|
|
58
|
+
3. **Macro expansion parity.** Go caps recursive expansion at 16 rounds; Node
|
|
59
|
+
(`nyks/string/replaceEnv`) recurses until the stack overflows on a
|
|
60
|
+
self-referencing value, and `$&`-style replacement patterns behave
|
|
61
|
+
differently. *Remedy:* port the bounded loop to Node or fix it upstream, and
|
|
62
|
+
add a cross-implementation fixture for pathological macros.
|
|
63
|
+
4. **Error swallowing.** `_read_token_cache` and the GitLab remote probe use
|
|
64
|
+
bare `catch(err) {}`; Go returns `nil` from `readTokenCache` for any cause.
|
|
65
|
+
A corrupt cache, a wrong key or a missing agent all look alike. *Remedy:* a
|
|
66
|
+
`--debug`-visible reason (the `vvauth:debug` logger exists in Node).
|
|
67
|
+
5. **HTTP hygiene.** Node uses `url.parse` (deprecated, lenient) and a 60 s
|
|
68
|
+
default timeout; Go uses `http.DefaultClient` with no timeout. Neither pins
|
|
69
|
+
or restricts TLS. *Remedy:* `url.URL`, an explicit `http.Client{Timeout}`,
|
|
70
|
+
and reject `http://` Vault addresses unless loopback.
|
|
71
|
+
6. **`install` rewrites `~/.bashrc` wholesale** (`0644`, trimmed, re-written),
|
|
72
|
+
and `FunctionExists` runs `bash -lc`, executing the user's whole login
|
|
73
|
+
profile. *Remedy:* append-only, and grep the file instead of spawning a
|
|
74
|
+
login shell.
|
|
75
|
+
7. **Release integrity.** `SHA256SUMS` is unsigned and the Linux binary is
|
|
76
|
+
unsigned; `release.yml` pulls `131/gh-actions@v1` by mutable tag. *Remedy:*
|
|
77
|
+
sign the checksum file (or publish build provenance) and pin the action by
|
|
78
|
+
commit.
|
|
79
|
+
|
|
80
|
+
## Scores
|
|
81
|
+
|
|
82
|
+
| Criterion | Score | Why |
|
|
83
|
+
| --- | ---: | --- |
|
|
84
|
+
| Coolness | 15/20 | One `.vauthrc`, one `venv`, and a Vault token appears from the SSH key you already carry, cached safely, identical from Node or a signed static binary. The macro language and the GitLab `CI_PROJECT_*` derivation make it a genuinely pleasant developer tool; what a repository's `./.vauthrc` may decide is the open question. |
|
|
85
|
+
| Robustness | 16/20 | Lease logic, cache isolation and Node/Go parity are tested and solid; a project `package.json` may pin the `vvauth` version it expects, in both runtimes. Loses on unbounded macro recursion in Node, swallowed errors and the absence of HTTP timeouts in Go. |
|
|
86
|
+
| Safety | 14/20 | Good secret handling: encrypted cache, escaped values, validated variable names, no clear-text fallbacks. Loses on the blanket trust in `./.vauthrc` (a cloned repository picks the Vault and gets a raw agent signature), on the agent-socket exposure of the cache, and on HTTP without timeouts or transport constraints. |
|
|
87
|
+
|
|
88
|
+
Codex (Claude Fable 5.1)
|