vvauth 2.2.0 → 2.4.0

package/README.md

@@ -63,10 +63,13 @@ vauth env --ir://json
 
 # Token cache
 
-Tokens are cached in `~/.vauth/token.json`, isolated by Vault and
+Tokens are cached in `~/.vauth/tokens/<session>.creds`, isolated by Vault and
 authentication. Tokens are reused, renewed within their lease’s final third, or
 replaced when expired. Existing `VAULT_TOKEN` takes precedence over cached tokens.
 
+Each session file is armored using `ssh-agent-crypt` and your SSH agent’s first
+key. Without an SSH agent, disk caching is disabled.
+
 Set `token_cache: false` in `.vauthrc` to disable disk cache reads and writes.
 
 ## Force reauthentication

package/index.js

@@ -6,9 +6,9 @@ const fs    = require('fs');
 const path  = require('path');
 const url   = require('url');
 const {createHash} = require('crypto');
+const {encrypt, decrypt} = require('ssh-agent-crypt');
 const {spawn, execFileSync} = require('child_process');
 const passthru = require('nyks/child_process/passthru');
-const wait     = require('nyks/child_process/wait');
 const boolPrompt = require('cnyks/prompt/bool');
 
 const {parse} = require('yaml');
@@ -89,6 +89,9 @@ class vvauth {
     }
 
 
+    if(!process.env.SSH_AUTH_SOCK)
+      this.rc.token_cache = false;
+
     this.VAULT_ADDR = this.rc.vault_addr || process.env.VAULT_ADDR; //might be null
     this.VAULT_TOKEN = process.env.VAULT_TOKEN;
 
@@ -112,40 +115,38 @@ class vvauth {
   }
 
   _token_cache_file() {
-    return path.join(os.homedir(), '.vauth', 'token.json');
+    return path.join(os.homedir(), '.vauth', 'tokens', this._token_cache_key() + '.creds');
   }
 
-  _read_token_cache() {
+  async _read_token_cache() {
     if(this.rc.token_cache === false)
-      return {version : 1, tokens : {}};
+      return;
     try {
-      const cache = JSON.parse(fs.readFileSync(this._token_cache_file(), 'utf8'));
-      if(cache.version === 1 && cache.tokens && typeof cache.tokens === 'object' && !Array.isArray(cache.tokens))
-        return cache;
+      const armor = fs.readFileSync(this._token_cache_file(), 'utf8');
+      return JSON.parse(await decrypt(armor));
     } catch(err) {}
-    return {version : 1, tokens : {}};
   }
 
-  _save_cached_token(token, metadata) {
+  async _save_cached_token(token, metadata) {
     if(this.rc.token_cache === false)
       return;
     const ttl = metadata.ttl === undefined ? metadata.lease_duration : metadata.ttl;
     const file = this._token_cache_file();
     const temporary = file + '.next';
     try {
-      const cache = this._read_token_cache();
-      const key = this._token_cache_key();
       const {lease_duration} = metadata;
-      cache.tokens[key] = {
+      const cache = {
         token, lease_duration, renewable : metadata.renewable === true,
         expires_at : ttl === 0 ? null : Date.now() + ttl * 1000,
       };
       fs.mkdirSync(path.dirname(file), {recursive : true, mode : 0o700});
-      fs.writeFileSync(temporary, JSON.stringify(cache, null, 2) + '\n', {mode : 0o600});
+      const identity = process.env.VAUTH_USER_IDENTITY || process.env.VAUTH_USER_MAIL;
+      const armor = await encrypt(JSON.stringify(cache), identity);
+      fs.writeFileSync(temporary, armor, {mode : 0o600});
       fs.renameSync(temporary, file);
     } catch(err) {
       // Cache failures must not prevent authentication or expose credentials.
-      logger.error('Could not write token cache (%s)', err.code || 'invalid cache');
+      console.error('Could not encrypt/write token cache; token not persisted');
     } finally {
       try { fs.unlinkSync(temporary); } catch(err) {}
     }
@@ -158,11 +159,16 @@ class vvauth {
   }
 
   async connect(renew = false) {
+    const {ssh_auth, jwt_auth} = this.rc;
+    if(!ssh_auth && !jwt_auth) {
+      this.VAULT_TOKEN = undefined;
+      return;
+    }
     if(this._connected && !renew)
       return this.VAULT_TOKEN;
     this._connected = false;
 
-    const cached = this._read_token_cache().tokens[this._token_cache_key()];
+    const cached = await this._read_token_cache();
     let token = this.VAULT_TOKEN || (cached && cached.token);
     const had_token = !!token;
     let metadata, operation = 'reused';
@@ -197,7 +203,6 @@ class vvauth {
     }
 
     if(!token) {
-      const {ssh_auth, jwt_auth} = this.rc;
       const agent_path = process.env.SSH_AUTH_SOCK || (process.platform === 'win32' ? 'pageant' : null);
       if(ssh_auth && agent_path) {
         metadata = await this._login_vault_ssh({...ssh_auth}, agent_path);
@@ -213,7 +218,7 @@ class vvauth {
 
     if(token) {
       if(operation !== 'reused' || !cached || cached.token !== token)
-        this._save_cached_token(token, metadata);
+        await this._save_cached_token(token, metadata);
       this._token_status(operation, metadata);
     }
     this.VAULT_TOKEN = token;
@@ -301,16 +306,7 @@ class vvauth {
     let {'ssh-agent-crypt' : agent } = this.rc;
     if(agent) {
       const {path, identity} = agent;
-      let child = spawn('ssh-agent-crypt', ["-decrypt", identity]);
-
-      child.stdin.end(fs.readFileSync(path));
-      child.stderr.pipe(process.stderr);
-
-      const [exit, body] = await Promise.all([wait(child, false), drain(child.stdout)]);
-      if(exit !== 0) {
-        console.error("Could not expand armored %s using %s", path, identity);
-        process.exit();
-      }
+      const body = await decrypt(fs.readFileSync(path), identity);
       const result = JSON.parse(body);
       secrets = {...secrets, ...result};
     }
@@ -445,7 +441,7 @@ class vvauth {
     let response = JSON.parse(await drain(res)).data;
     if(!Number.isFinite(response.ttl) || response.ttl < 0)
       throw new Error('Invalid Vault token TTL');
-    const cached = this._read_token_cache().tokens[this._token_cache_key()];
+    const cached = await this._read_token_cache();
     if(cached && cached.token === token)
       response.lease_duration = cached.lease_duration;
     else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vvauth",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Vault Auth helper",
   "main": "index.js",
   "bin": {
@@ -18,7 +18,7 @@
     "mout": "^1.2.4",
     "nyks": "^6.15.0",
     "semver": "^7.5.4",
-    "ssh-agent-crypt": "^1.0.1",
+    "ssh-agent-crypt": "^1.2.0",
     "ssh2": "^1.16.0",
     "yaml": "^2.6.1"
   },

package/test/token-cache.js

@@ -1,21 +1,58 @@
 'use strict';
 
 const assert = require('node:assert/strict');
-const {test} = require('node:test');
+const {test, before, after} = require('node:test');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const http = require('http');
-const {execFile, spawn} = require('child_process');
+const {execFile, spawn, spawnSync} = require('child_process');
 const {promisify, format} = require('util');
 const exec = promisify(execFile);
 const Vauth = require('../index');
 
+const {encrypt, decrypt} = require('ssh-agent-crypt');
+const readCache = async file => JSON.parse(await decrypt(fs.readFileSync(file, 'utf8')));
+const writeCache = async (file, cache) => fs.writeFileSync(file, await encrypt(JSON.stringify(cache)));
+let agentDirectory, agentPid;
+const previousSocket = process.env.SSH_AUTH_SOCK;
+const previousIdentity = process.env.VAUTH_USER_IDENTITY;
+const previousMail = process.env.VAUTH_USER_MAIL;
+
+before(() => {
+  delete process.env.VAUTH_USER_IDENTITY;
+  delete process.env.VAUTH_USER_MAIL;
+  agentDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'vvauth-agent-'));
+  const key = path.join(agentDirectory, 'key');
+  assert.equal(spawnSync('ssh-keygen', ['-q', '-t', 'ed25519', '-N', '', '-f', key]).status, 0);
+  const agent = spawnSync('ssh-agent', ['-s'], {encoding : 'utf8'});
+  assert.equal(agent.status, 0);
+  process.env.SSH_AUTH_SOCK = agent.stdout.match(/SSH_AUTH_SOCK=([^;]+)/)[1];
+  agentPid = agent.stdout.match(/SSH_AGENT_PID=(\d+)/)[1];
+  assert.equal(spawnSync('ssh-add', [key]).status, 0);
+});
+
+after(() => {
+  for(const [name, value] of [['VAUTH_USER_IDENTITY', previousIdentity], ['VAUTH_USER_MAIL', previousMail]]) {
+    if(value === undefined)
+      delete process.env[name];
+    else
+      process.env[name] = value;
+  }
+  if(agentPid)
+    process.kill(Number(agentPid));
+  if(previousSocket === undefined)
+    delete process.env.SSH_AUTH_SOCK;
+  else
+    process.env.SSH_AUTH_SOCK = previousSocket;
+  fs.rmSync(agentDirectory, {recursive : true, force : true});
+});
+
 const HOUR = 60 * 60;
 
 async function fixture(t, options = {}) {
   const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'vvauth-test-'));
-  const file = path.join(directory, '.vauth', 'token.json');
+  let file;
   const requests = [];
   const server = http.createServer(async (req, res) => {
     let body = '';
@@ -48,20 +85,22 @@ async function fixture(t, options = {}) {
     const instance = Object.create(Vauth.prototype);
     instance.rc = {jwt_auth : {path : 'jwt', jwt : 'test-jwt', role : 'test-role'}};
     instance.VAULT_ADDR = `http://127.0.0.1:${server.address().port}`;
-    instance._token_cache_file = () => file;
+    instance._token_cache_file = () => path.join(directory, '.vauth', 'tokens', instance._token_cache_key() + '.creds');
     return instance;
   };
-  const remaining = (instance, ttl) => {
-    const cache = JSON.parse(fs.readFileSync(file, 'utf8'));
-    cache.tokens[instance._token_cache_key()].expires_at = ttl === 0 ? null : Date.now() + ttl * 1000;
-    fs.writeFileSync(file, JSON.stringify(cache));
+  file = client()._token_cache_file();
+  const remaining = async (instance, ttl) => {
+    const file = instance._token_cache_file();
+    const cache = (await readCache(file));
+    cache.expires_at = ttl === 0 ? null : Date.now() + ttl * 1000;
+    await writeCache(file, cache);
   };
-  const seed = (instance, lease = 12 * HOUR) => {
-    instance._save_cached_token('cached-token', {lease_duration : lease, renewable : options.renewable !== false});
+  const seed = async (instance, lease = 12 * HOUR) => {
+    await instance._save_cached_token('cached-token', {lease_duration : lease, renewable : options.renewable !== false});
     if(options.ttl !== undefined)
-      remaining(instance, options.ttl);
+      await remaining(instance, options.ttl);
   };
-  const read = instance => JSON.parse(fs.readFileSync(file, 'utf8')).tokens[instance._token_cache_key()];
+  const read = async instance => readCache(instance._token_cache_file());
   return {client, seed, read, requests, file, remaining};
 }
 
@@ -69,31 +108,31 @@ test('login persists a token; a new instance reuses it without logging in', asyn
   const {client, read, requests, file} = await fixture(t);
   const first = client();
   assert.equal(await first.connect(), 'fresh-token');
-  assert.equal(read(first).token, 'fresh-token');
-  assert.ok(read(first).expires_at > Date.now() + 23 * HOUR * 1000);
+  assert.equal((await read(first)).token, 'fresh-token');
+  assert.ok((await read(first)).expires_at > Date.now() + 23 * HOUR * 1000);
   assert.equal(fs.statSync(file).mode & 0o777, 0o600);
   assert.equal(fs.statSync(path.dirname(file)).mode & 0o777, 0o700);
   const second = client();
   assert.equal(await second.connect(), 'fresh-token');
   assert.deepEqual(requests.map(req => req.path), ['/v1/auth/jwt/login']);
-  assert.deepEqual(fs.readdirSync(path.dirname(file)), ['token.json']);
+  assert.deepEqual(fs.readdirSync(path.dirname(file)), [path.basename(file)]);
 });
 
 test('a token in the last third of its lease is renewed and saved', async t => {
   const {client, seed, read, requests} = await fixture(t, {ttl : HOUR});
   const instance = client();
-  seed(instance, 12 * HOUR);
+  await seed(instance, 12 * HOUR);
   assert.equal(await instance.connect(), 'cached-token');
   assert.deepEqual(requests.map(req => req.path), ['/v1/auth/token/renew-self']);
   assert.equal(requests[0].method, 'POST');
   assert.equal(requests[0].token, 'cached-token');
-  assert.ok(read(instance).expires_at > Date.now() + 23 * HOUR * 1000);
+  assert.ok((await read(instance)).expires_at > Date.now() + 23 * HOUR * 1000);
 });
 
 test('more than one third remaining does not trigger renewal', async t => {
   const {client, seed, requests} = await fixture(t, {ttl : 4 * HOUR + 1});
   const instance = client();
-  seed(instance);
+  await seed(instance);
   assert.equal(await instance.connect(), 'cached-token');
   assert.equal(requests.length, 0);
 });
@@ -101,19 +140,19 @@ test('more than one third remaining does not trigger renewal', async t => {
 test('expired cached tokens are replaced with a new persisted login', async t => {
   const {client, seed, read, requests, file} = await fixture(t);
   const instance = client();
-  seed(instance);
-  const cache = JSON.parse(fs.readFileSync(file, 'utf8'));
-  cache.tokens[instance._token_cache_key()].expires_at = Date.now() - 1000;
-  fs.writeFileSync(file, JSON.stringify(cache));
+  await seed(instance);
+  const cache = (await readCache(file));
+  cache.expires_at = Date.now() - 1000;
+  await writeCache(file, cache);
   assert.equal(await instance.connect(), 'fresh-token');
-  assert.equal(read(instance).token, 'fresh-token');
+  assert.equal((await read(instance)).token, 'fresh-token');
   assert.deepEqual(requests.map(req => req.path), ['/v1/auth/jwt/login']);
 });
 
 test('cached tokens are reused without checking revocation', async t => {
   const {client, seed, requests} = await fixture(t, {lookup_status : 403});
   const instance = client();
-  seed(instance);
+  await seed(instance);
   assert.equal(await instance.connect(), 'cached-token');
   assert.deepEqual(requests, []);
   await assert.rejects(instance._lookup_token(instance.VAULT_TOKEN));
@@ -122,7 +161,7 @@ test('cached tokens are reused without checking revocation', async t => {
 test('nonrenewable tokens nearing expiry trigger reauthentication', async t => {
   const {client, seed, requests} = await fixture(t, {ttl : HOUR, renewable : false});
   const instance = client();
-  seed(instance);
+  await seed(instance);
   assert.equal(await instance.connect(), 'fresh-token');
   assert.deepEqual(requests.map(req => req.path), ['/v1/auth/jwt/login']);
 });
@@ -131,9 +170,9 @@ for(const status of [400, 403]) {
   test(`rejected renewal (${status}) triggers a new persisted login`, async t => {
     const {client, seed, read, requests} = await fixture(t, {ttl : HOUR, renew_status : status});
     const instance = client();
-    seed(instance);
+    await seed(instance);
     assert.equal(await instance.connect(), 'fresh-token');
-    assert.equal(read(instance).token, 'fresh-token');
+    assert.equal((await read(instance)).token, 'fresh-token');
     assert.deepEqual(requests.map(req => req.path), ['/v1/auth/token/renew-self', '/v1/auth/jwt/login']);
   });
 }
@@ -141,7 +180,7 @@ for(const status of [400, 403]) {
 test('server failures do not generate extra tokens, and connect can be retried', async t => {
   const {client, seed, requests} = await fixture(t, {lookup_status : 500});
   const instance = client();
-  seed(instance);
+  await seed(instance);
   instance.VAULT_TOKEN = 'uncached-token';
   await assert.rejects(instance.connect());
   await assert.rejects(instance.connect());
@@ -151,7 +190,7 @@ test('server failures do not generate extra tokens, and connect can be retried',
 test('renewal server failures do not generate extra tokens', async t => {
   const {client, seed, requests} = await fixture(t, {ttl : HOUR, renew_status : 500});
   const instance = client();
-  seed(instance);
+  await seed(instance);
   await assert.rejects(instance.connect());
   assert.deepEqual(requests.map(req => req.path), ['/v1/auth/token/renew-self']);
 });
@@ -159,10 +198,10 @@ test('renewal server failures do not generate extra tokens', async t => {
 test('an existing environment token is respected and cached', async t => {
   const {client, seed, read, requests} = await fixture(t);
   const instance = client();
-  seed(instance);
+  await seed(instance);
   instance.VAULT_TOKEN = 'environment-token';
   assert.equal(await instance.connect(), 'environment-token');
-  assert.equal(read(instance).token, 'environment-token');
+  assert.equal((await read(instance)).token, 'environment-token');
   assert.equal(requests[0].token, 'environment-token');
   assert.equal(requests.length, 1);
 });
@@ -170,34 +209,35 @@ test('an existing environment token is respected and cached', async t => {
 test('nonexpiring tokens are reused without renewal', async t => {
   const {client, seed, read, requests} = await fixture(t, {ttl : 0});
   const instance = client();
-  seed(instance, 0);
+  await seed(instance, 0);
   assert.equal(await instance.connect(), 'cached-token');
-  assert.equal(read(instance).expires_at, null);
+  assert.equal((await read(instance)).expires_at, null);
   assert.equal(requests.length, 0);
 });
 
 test('corrupt caches are replaced with a valid cache', async t => {
   const {client, read, file} = await fixture(t);
-  fs.mkdirSync(path.dirname(file));
+  fs.mkdirSync(path.dirname(file), {recursive : true});
   fs.writeFileSync(file, '{broken');
   const instance = client();
   assert.equal(await instance.connect(), 'fresh-token');
-  assert.equal(read(instance).token, 'fresh-token');
+  assert.equal((await read(instance)).token, 'fresh-token');
 });
 
 test('cache entries are isolated by Vault address and authentication configuration', async t => {
   const {client, seed, read, file} = await fixture(t);
   const first = client();
-  seed(first);
+  await seed(first);
   const second = client();
   second.rc.jwt_auth.role = 'other-role';
   assert.equal(await second.connect(), 'fresh-token');
-  assert.equal(read(first).token, 'cached-token');
-  assert.equal(read(second).token, 'fresh-token');
+  assert.notEqual(first._token_cache_file(), second._token_cache_file());
+  assert.equal((await read(first)).token, 'cached-token');
+  assert.equal((await read(second)).token, 'fresh-token');
   const third = client();
   third.VAULT_ADDR = 'http://other-vault.test';
   assert.notEqual(third._token_cache_key(), first._token_cache_key());
-  assert.equal(Object.keys(JSON.parse(fs.readFileSync(file, 'utf8')).tokens).length, 2);
+  assert.equal(fs.readdirSync(path.dirname(file)).length, 2);
   assert.ok(!fs.readFileSync(file, 'utf8').includes('test-jwt'));
 });
 
@@ -211,38 +251,41 @@ test('repeated connect calls reuse the established connection', async t => {
 
 test('an unwritable cache does not prevent login', async t => {
   const {client, file} = await fixture(t);
+  fs.mkdirSync(path.dirname(path.dirname(file)), {recursive : true});
   fs.writeFileSync(path.dirname(file), 'not a directory');
   assert.equal(await client().connect(), 'fresh-token');
 });
 
-test('an invalid token without an auth method fails rather than exporting undefined', async t => {
+test('without an auth method inherited tokens and caches are ignored', async t => {
   const {client, seed} = await fixture(t, {lookup_status : 403});
   const instance = client();
   instance.rc = {};
-  seed(instance);
+  await seed(instance);
   instance.VAULT_TOKEN = 'uncached-token';
-  await assert.rejects(instance.connect(), /no authentication method/);
+  instance._read_token_cache = async () => { throw new Error('No auth: no cache lookup'); };
+  assert.equal(await instance.connect(), undefined);
+  assert.equal(instance.VAULT_TOKEN, undefined);
 });
 
 test('--renew ignores both environment and cached tokens and saves a new token', async t => {
   const {client, seed, read, requests} = await fixture(t);
   const instance = client();
-  seed(instance);
+  await seed(instance);
   instance.VAULT_TOKEN = 'environment-token';
   assert.equal(await instance.connect(true), 'fresh-token');
   assert.deepEqual(requests.map(req => req.path), ['/v1/auth/jwt/login']);
-  assert.equal(read(instance).token, 'fresh-token');
-  assert.ok(read(instance).expires_at > Date.now() + 23 * HOUR * 1000);
+  assert.equal((await read(instance)).token, 'fresh-token');
+  assert.ok((await read(instance)).expires_at > Date.now() + 23 * HOUR * 1000);
 });
 
 test('--renew replaces the token of a previously connected instance', async t => {
   const {client, seed, read, requests} = await fixture(t);
   const instance = client();
-  seed(instance);
+  await seed(instance);
   await instance.connect();
   assert.equal(await instance.connect(true), 'fresh-token');
   assert.deepEqual(requests.map(req => req.path), ['/v1/auth/jwt/login']);
-  assert.equal(read(instance).token, 'fresh-token');
+  assert.equal((await read(instance)).token, 'fresh-token');
 });
 
 test('each successive --renew call forces a new login', async t => {
@@ -253,11 +296,11 @@ test('each successive --renew call forces a new login', async t => {
   assert.equal(requests.length, 2);
 });
 
-test('--renew without an authentication method fails even with no cached token', async t => {
+test('--renew without an authentication method remains a no-op', async t => {
   const {client} = await fixture(t);
   const instance = client();
   instance.rc = {};
-  await assert.rejects(instance.connect(true), /no authentication method/);
+  assert.equal(await instance.connect(true), undefined);
 });
 
 for(const flag of ['renew']) {
@@ -274,13 +317,13 @@ for(const flag of ['renew']) {
     test(`real CLI ${command} --${flag} generates and caches a new token`, async t => {
       const {client, seed, read, requests, file} = await fixture(t);
       const instance = client();
-      seed(instance);
-      const home = path.dirname(path.dirname(file));
+      await seed(instance);
+      const home = path.dirname(path.dirname(path.dirname(file)));
       const rc = path.join(home, '.vauthrc');
       fs.writeFileSync(rc, JSON.stringify({vault_addr : instance.VAULT_ADDR, ...instance.rc}));
       const options = {
         cwd : home,
-        env : {...process.env, HOME : home, VAUTHRC : rc, VAULT_TOKEN : 'environment-token', SSH_AUTH_SOCK : ''},
+        env : {...process.env, HOME : home, VAUTHRC : rc, VAULT_TOKEN : 'environment-token', SSH_AUTH_SOCK : process.env.SSH_AUTH_SOCK},
       };
       const cli = path.resolve(__dirname, '..', 'index.js');
       const output = await exec(process.execPath, [cli, command, '--source', `--${flag}`], options);
@@ -292,7 +335,7 @@ for(const flag of ['renew']) {
       assert.ok(!output.stderr.includes('environment-token'));
       assert.deepEqual(requests.filter(req => !req.path.startsWith('/v1/identity/')).map(req => req.path), command === 'env'
         ? ['/v1/auth/jwt/login', '/v1/auth/token/lookup-self'] : ['/v1/auth/jwt/login']);
-      assert.equal(read(instance).token, 'fresh-token');
+      assert.equal((await read(instance)).token, 'fresh-token');
       assert.equal(fs.statSync(file).mode & 0o777, 0o600);
       requests.length = 0;
       const reused = await exec(process.execPath, [cli, command, '--source'], {
@@ -309,8 +352,8 @@ for(const flag of ['renew']) {
 test('installed venv forwards --renew through the real CLI', async t => {
   const {client, seed, read, requests, file} = await fixture(t);
   const instance = client();
-  seed(instance);
-  const home = path.dirname(path.dirname(file));
+  await seed(instance);
+  const home = path.dirname(path.dirname(path.dirname(file)));
   const original_home = os.homedir;
   instance._function_exists = async () => 1;
   try {
@@ -328,7 +371,7 @@ test('installed venv forwards --renew through the real CLI', async t => {
   fs.writeFileSync(rc, JSON.stringify({vault_addr : instance.VAULT_ADDR, ...instance.rc}));
   const options = {
     cwd : home,
-    env : {...process.env, HOME : home, VAUTHRC : rc, VAULT_TOKEN : '', SSH_AUTH_SOCK : '', PATH : `${bin}:${process.env.PATH}`},
+    env : {...process.env, HOME : home, VAUTHRC : rc, VAULT_TOKEN : '', SSH_AUTH_SOCK : process.env.SSH_AUTH_SOCK, PATH : `${bin}:${process.env.PATH}`},
   };
   const initial = await exec('bash', ['-c', `${declaration}\nvenv; printf '%s' "$VAULT_TOKEN"`], options);
   assert.equal(initial.stdout, 'cached-token');
@@ -341,7 +384,7 @@ test('installed venv forwards --renew through the real CLI', async t => {
     assert.equal(output.stderr.split('\n').filter(line => line === `Vauth token: generated · ${instance.VAULT_ADDR} · 1d`).length, 1);
     assert.ok(!output.stderr.includes('Vauth token: renewed'));
     assert.ok(!output.stderr.includes('fresh-token'));
-    assert.equal(read(instance).token, 'fresh-token');
+    assert.equal((await read(instance)).token, 'fresh-token');
   }
   assert.equal(requests.filter(req => req.path.endsWith('/login')).length, 1);
   assert.ok(!requests.some(req => req.path.endsWith('/renew-self')));
@@ -350,7 +393,7 @@ test('installed venv forwards --renew through the real CLI', async t => {
 for(const answer of ['yes', 'no', '']) {
   test(`install asks before overriding an existing function: ${JSON.stringify(answer)}`, async t => {
     const {file} = await fixture(t);
-    const home = path.dirname(path.dirname(file));
+    const home = path.dirname(path.dirname(path.dirname(file)));
     const bashrc = path.join(home, '.bashrc');
     const original = '# before\nfunction venv() { source <(/usr/bin/env vauth env --source); }\n# after\n';
     fs.writeFileSync(bashrc, original);
@@ -430,7 +473,7 @@ for(const options of [
   test(`one final status per connection: ${JSON.stringify(options)}`, async t => {
     const {client, seed} = await fixture(t, options);
     const instance = client();
-    seed(instance);
+    await seed(instance);
     const calls = [];
     instance._token_status = (operation, metadata) => {
       calls.push(...captureStatus(() => Vauth.prototype._token_status.call(instance, operation, metadata)));
@@ -445,7 +488,7 @@ for(const options of [
 test('failed connections never announce successful token status', async t => {
   const {client, seed} = await fixture(t, {lookup_status : 500});
   const instance = client();
-  seed(instance);
+  await seed(instance);
   instance.VAULT_TOKEN = 'uncached-token';
   const calls = [];
   instance._token_status = operation => calls.push(operation);
@@ -464,10 +507,10 @@ for(const [lease, remaining, renew] of [
   test(`proportional threshold: lease=${lease}, remaining=${remaining}`, async t => {
     const {client, seed, read, requests} = await fixture(t, {ttl : remaining});
     const instance = client();
-    seed(instance, lease);
+    await seed(instance, lease);
     await instance.connect();
     assert.equal(requests.some(req => req.path.endsWith('/renew-self')), renew);
-    assert.equal(read(instance).lease_duration, renew ? 24 * HOUR : lease);
+    assert.equal((await read(instance)).lease_duration, renew ? 24 * HOUR : lease);
   });
 }
 
@@ -475,13 +518,13 @@ test('lookups never reset the original lease duration', async t => {
   const options = {ttl : 20 * HOUR};
   const {client, seed, read, requests, remaining} = await fixture(t, options);
   const instance = client();
-  seed(instance, 24 * HOUR);
+  await seed(instance, 24 * HOUR);
   await instance.connect();
-  assert.equal(read(instance).lease_duration, 24 * HOUR);
-  remaining(instance, 12 * HOUR);
+  assert.equal((await read(instance)).lease_duration, 24 * HOUR);
+  await remaining(instance, 12 * HOUR);
   await client().connect();
-  assert.equal(read(instance).lease_duration, 24 * HOUR);
-  remaining(instance, 8 * HOUR);
+  assert.equal((await read(instance)).lease_duration, 24 * HOUR);
+  await remaining(instance, 8 * HOUR);
   await client().connect();
   assert.equal(requests.filter(req => req.path.endsWith('/renew-self')).length, 1);
 });
@@ -490,10 +533,10 @@ test('renewal updates the lease baseline to the newly granted duration', async t
   const options = {ttl : 20 * 60};
   const {client, seed, read, requests, remaining} = await fixture(t, options);
   const instance = client();
-  seed(instance, HOUR);
+  await seed(instance, HOUR);
   await instance.connect();
-  assert.equal(read(instance).lease_duration, 24 * HOUR);
-  remaining(instance, 8 * HOUR);
+  assert.equal((await read(instance)).lease_duration, 24 * HOUR);
+  await remaining(instance, 8 * HOUR);
   await client().connect();
   assert.equal(requests.filter(req => req.path.endsWith('/renew-self')).length, 2);
 });
@@ -501,7 +544,7 @@ test('renewal updates the lease baseline to the newly granted duration', async t
 test('normal reuse never writes the token cache', async t => {
   const {client, seed, file, requests} = await fixture(t);
   const instance = client();
-  seed(instance);
+  await seed(instance);
   instance.VAULT_TOKEN = 'cached-token';
   const before = fs.readFileSync(file, 'utf8');
   const stat = fs.statSync(file);
@@ -520,7 +563,7 @@ test('lookup returns the lease duration and preserves a cached renewal baseline'
   const uncached = await instance._lookup_token('environment-token');
   assert.equal(uncached.lease_duration, 24 * HOUR);
   assert.equal(uncached.ttl, HOUR);
-  seed(instance, 12 * HOUR);
+  await seed(instance, 12 * HOUR);
   const cached = await instance._lookup_token('cached-token');
   assert.equal(cached.lease_duration, 12 * HOUR);
   assert.equal(requests.length, 2);
@@ -539,7 +582,7 @@ test('token_cache false skips all cache filesystem access', async t => {
 test('token_cache false ignores existing tokens on disk without deleting them', async t => {
   const {client, seed, requests, file} = await fixture(t);
   const instance = client();
-  seed(instance);
+  await seed(instance);
   const before = fs.readFileSync(file, 'utf8');
   instance.rc.token_cache = false;
   assert.equal(await instance.connect(), 'fresh-token');
@@ -563,14 +606,14 @@ test('token_cache false still respects an environment token without persisting i
 test('real CLI reads token_cache false from .vauthrc', async t => {
   const {client, file, requests} = await fixture(t);
   const instance = client();
-  const home = path.dirname(path.dirname(file));
+  const home = path.dirname(path.dirname(path.dirname(file)));
   const rc = path.join(home, '.vauthrc');
   fs.writeFileSync(rc, JSON.stringify({vault_addr : instance.VAULT_ADDR, ...instance.rc, token_cache : false}));
   const cli = path.resolve(__dirname, '..', 'index.js');
   for(let i = 0; i < 2; i++) {
     const output = await exec(process.execPath, [cli, 'login', '--source'], {
       cwd : home,
-      env : {...process.env, HOME : home, VAUTHRC : rc, VAULT_TOKEN : '', SSH_AUTH_SOCK : ''},
+      env : {...process.env, HOME : home, VAUTHRC : rc, VAULT_TOKEN : '', SSH_AUTH_SOCK : process.env.SSH_AUTH_SOCK},
     });
     assert.ok(output.stdout.includes("export VAULT_TOKEN='fresh-token'"));
     assert.ok(output.stderr.includes('Vauth token: generated'));
@@ -578,3 +621,174 @@ test('real CLI reads token_cache false from .vauthrc', async t => {
   assert.equal(fs.existsSync(file), false);
   assert.equal(requests.filter(req => req.path.endsWith('/login')).length, 2);
 });
+
+test('disk cache contains only armor, interoperable with ssh-agent-crypt CLI', async t => {
+  const {client, file} = await fixture(t);
+  const instance = client();
+  await instance.connect();
+  const armor = fs.readFileSync(file, 'utf8');
+  assert.match(armor, /^ssh-agent-crypt:v2:/);
+  assert.ok(!armor.includes('fresh-token'));
+  assert.ok(!armor.includes('lease_duration'));
+  assert.ok(!armor.includes('test-jwt'));
+  const cli = require.resolve('ssh-agent-crypt/bin/ssh-agent-crypt');
+  const decoded = spawnSync('bash', [cli, '-decrypt'], {input : armor, encoding : 'utf8'});
+  assert.equal(decoded.status, 0);
+  assert.equal(JSON.parse(decoded.stdout).token, 'fresh-token');
+});
+
+test('a plaintext cache is not accepted as a token cache', async t => {
+  const {client, file, requests} = await fixture(t);
+  const instance = client();
+  fs.mkdirSync(path.dirname(file), {recursive : true});
+  fs.writeFileSync(file, JSON.stringify({token : 'plaintext-token', lease_duration : 86400, expires_at : Date.now() + 86400000}));
+  assert.equal(await instance.connect(), 'fresh-token');
+  assert.deepEqual(requests.map(req => req.path), ['/v1/auth/jwt/login']);
+  assert.match(fs.readFileSync(file, 'utf8'), /^ssh-agent-crypt:v2:/);
+});
+
+test('without an SSH agent cache is skipped silently', async t => {
+  const {client, file} = await fixture(t);
+  const instance = client();
+  instance._token_cache_file = () => { throw new Error('No agent: no disk access'); };
+  const socket = process.env.SSH_AUTH_SOCK;
+  const original = console.error;
+  const messages = [];
+  try {
+    delete process.env.SSH_AUTH_SOCK;
+    instance.rc.token_cache = false;
+    console.error = (...args) => messages.push(format(...args));
+    assert.equal(await instance.connect(), 'fresh-token');
+  } finally {
+    process.env.SSH_AUTH_SOCK = socket;
+    console.error = original;
+  }
+  assert.equal(fs.existsSync(file), false);
+  assert.equal(fs.existsSync(file + '.next'), false);
+  assert.ok(!messages.some(message => message.includes('token not persisted')));
+  assert.ok(!messages.join('\n').includes('fresh-token'));
+});
+
+test('without an SSH agent existing armor is left untouched', async t => {
+  const {client, seed, file} = await fixture(t);
+  const instance = client();
+  await seed(instance);
+  const before = fs.readFileSync(file, 'utf8');
+  const socket = process.env.SSH_AUTH_SOCK;
+  try {
+    delete process.env.SSH_AUTH_SOCK;
+    instance.rc.token_cache = false;
+    await instance._save_cached_token('replacement-token', {lease_duration : 86400, renewable : true});
+  } finally {
+    process.env.SSH_AUTH_SOCK = socket;
+  }
+  assert.equal(fs.readFileSync(file, 'utf8'), before);
+  assert.equal(fs.existsSync(file + '.next'), false);
+});
+
+
+test('constructor disables token caching when no SSH agent is configured', async t => {
+  const {client, file} = await fixture(t);
+  const instance = client();
+  const home = path.dirname(path.dirname(path.dirname(file)));
+  const rc = path.join(home, '.vauthrc');
+  fs.writeFileSync(rc, JSON.stringify({vault_addr : instance.VAULT_ADDR, ...instance.rc, token_cache : true}));
+  const module_path = path.resolve(__dirname, '..', 'index.js');
+  const script = `const Vauth = require(${JSON.stringify(module_path)});
+    const instance = new Vauth();
+    process.stdout.write(String(instance.rc.token_cache));
+    instance.login().catch(() => process.exit(1));`;
+  const output = await exec(process.execPath, ['-e', script], {
+    cwd : home,
+    env : {...process.env, HOME : home, VAUTHRC : rc, VAULT_TOKEN : '', SSH_AUTH_SOCK : ''},
+  });
+  assert.equal(output.stdout.trim(), 'false');
+  assert.ok(!output.stderr.includes('token not persisted'));
+  assert.equal(fs.existsSync(file), false);
+});
+
+
+for(const selected of ['identity', 'mail', 'default']) {
+  test(`cache encryption selects ${selected}; decryption uses embedded fingerprint`, async t => {
+    const {client, file} = await fixture(t);
+    const instance = client();
+    const directory = path.dirname(path.dirname(path.dirname(file)));
+    const key = path.join(directory, 'selected-key');
+    const comment = 'selected-cache@test';
+    assert.equal(spawnSync('ssh-keygen', ['-q', '-t', 'ed25519', '-N', '', '-C', comment, '-f', key]).status, 0);
+    assert.equal(spawnSync('ssh-add', [key]).status, 0);
+    try {
+      if(selected === 'identity') {
+        process.env.VAUTH_USER_IDENTITY = comment;
+        process.env.VAUTH_USER_MAIL = 'missing-key@test';
+      } else if(selected === 'mail') {
+        process.env.VAUTH_USER_MAIL = comment;
+      }
+      assert.equal(await instance.connect(), 'fresh-token');
+      const fingerprint = spawnSync('ssh-keygen', ['-lf', key + '.pub'], {encoding : 'utf8'}).stdout.split(/\s+/)[1];
+      const armor = fs.readFileSync(file, 'utf8');
+      assert.equal(armor.startsWith(`ssh-agent-crypt:v2:${fingerprint}.`), selected !== 'default');
+      delete process.env.VAUTH_USER_IDENTITY;
+      delete process.env.VAUTH_USER_MAIL;
+      assert.equal(await client().connect(), 'fresh-token');
+    } finally {
+      spawnSync('ssh-add', ['-d', key]);
+      delete process.env.VAUTH_USER_IDENTITY;
+      delete process.env.VAUTH_USER_MAIL;
+    }
+  });
+}
+
+for(const explicit of [false, true]) {
+  test(`.creds uses the JS module without a CLI (explicit identity=${explicit})`, async t => {
+    const {client, file} = await fixture(t);
+    const instance = client();
+    const credentials = path.join(path.dirname(path.dirname(path.dirname(file))), '.creds');
+    const identity = spawnSync('ssh-add', ['-l'], {encoding : 'utf8'}).stdout.split(/\s+/)[1];
+    fs.writeFileSync(credentials, await encrypt(JSON.stringify({TEST_SECRET : 'module-secret'})));
+    instance.rc['ssh-agent-crypt'] = {path : credentials};
+    if(explicit)
+      instance.rc['ssh-agent-crypt'].identity = identity;
+    instance.rc.env = {map : {EXPORTED_SECRET : '$${secrets.TEST_SECRET}'}};
+    instance._vault_get_profile = async () => ({profile : {}, database : {}});
+    const previousPath = process.env.PATH;
+    try {
+      process.env.PATH = path.dirname(credentials);
+      const env = await instance.env();
+      assert.equal(env.EXPORTED_SECRET, 'module-secret');
+    } finally {
+      process.env.PATH = previousPath;
+    }
+  });
+}
+
+test('.creds decryption failures reject instead of exiting successfully', async t => {
+  const {client, file} = await fixture(t);
+  const instance = client();
+  const credentials = path.join(path.dirname(path.dirname(path.dirname(file))), '.creds');
+  fs.writeFileSync(credentials, 'not an armored payload');
+  instance.rc['ssh-agent-crypt'] = {path : credentials};
+  instance._vault_get_profile = async () => ({profile : {}, database : {}});
+  await assert.rejects(instance.env(), /Unsupported format header/);
+});
+
+for(const inherited of ['', 'inherited-token']) {
+  test(`local .creds environment works offline with inherited token=${!!inherited}`, async t => {
+    const {client, file, requests} = await fixture(t, {lookup_status : 503});
+    const instance = client();
+    const credentials = path.join(path.dirname(path.dirname(path.dirname(file))), '.creds');
+    fs.writeFileSync(credentials, await encrypt(JSON.stringify({ARM_CLIENT_SECRET : 'local-secret', VAULT_TOKEN : 'local-token'})));
+    instance.rc = {
+      'ssh-agent-crypt' : {path : credentials},
+      env : {map : {ARM_CLIENT_SECRET : '$${secrets.ARM_CLIENT_SECRET}', VAULT_TOKEN : '$${secrets.VAULT_TOKEN}'}},
+    };
+    instance.VAULT_TOKEN = inherited;
+    instance._lookup_token = async () => { throw new Error('Local environment must not contact Vault'); };
+    instance._read_token_cache = async () => { throw new Error('Local environment must not read the token cache'); };
+    const env = await instance.env();
+    assert.equal(env.ARM_CLIENT_SECRET, 'local-secret');
+    assert.equal(env.VAULT_TOKEN, 'local-token');
+    assert.equal(env.VAULT_ADDR, instance.VAULT_ADDR);
+    assert.deepEqual(requests, []);
+  });
+}