@sharedenv/cli 0.0.0-stage → 1.0.0

package/lib/auth.js

@@ -0,0 +1,70 @@
+// Signing in and unlocking the vault. The master password never leaves this process:
+// the server receives a verifier derived from it, and the private key is unwrapped
+// locally from the keyring the server stores sealed.
+
+import { Wallet, assertKdfParams, deriveAuthVerifier, unwrapPrivateKey } from './crypto.js';
+import { expectOk } from './api.js';
+
+const wallet = new Wallet();
+
+// `authKdf` comes from the server: the verifier is domain-separated from the wrap key,
+// so a server that serves the keyring's `kdf` as `authKdf` still never receives the key
+// that unwraps the vault.
+//
+// `otp` answers the second factor when the account has one: a code, or an async function
+// returning one. Any code the API accepts works — authenticator, mail or recovery code.
+export async function login(client, { identifier, password, otp }) {
+  const pre = expectOk(
+    await client.call('GET', `/auth/prelogin?identifier=${encodeURIComponent(identifier)}`),
+    'cannot sign in'
+  );
+  if (!pre?.authKdf) throw new Error('cannot sign in: the server sent no login parameters');
+  const authVerifier = await deriveAuthVerifier(password, pre.authKdf);
+  const session = expectOk(
+    await client.call('POST', '/auth/sign-in', { identifier, authVerifier }),
+    'cannot sign in'
+  );
+  if (session?.use2fa) {
+    const code = typeof otp === 'function' ? await otp() : otp;
+    if (!code) throw new Error('this account requires a two-factor code');
+    expectOk(
+      await client.call('POST', '/auth/2fa/validate', { code: String(code).trim() }),
+      'two-factor code refused'
+    );
+  }
+  return session;
+}
+
+// Our public key, DERIVED from the private key we hold — never the server's copy.
+export function publicKeyOf(privateKey) {
+  return wallet.keypass.publicFromPrivate(privateKey);
+}
+
+// → the account's private key, in memory only.
+export async function unlockPrivateKey(client, password) {
+  const keyring = expectOk(await client.call('GET', '/keyring/me'), 'cannot read your keyring');
+  if (!keyring?.encPrivateKey) {
+    throw new Error('this account has no keyring yet: open the web app once to create it');
+  }
+  // The KDF parameters come from the server. Below the floor, the password would be
+  // stretched by almost nothing — an offline attack, not a typo: say so.
+  try {
+    assertKdfParams(keyring.kdf);
+  } catch (err) {
+    throw new Error(
+      `refusing to unlock: the server sent key-derivation parameters below the accepted floor (${err.message})`
+    );
+  }
+  let privateKey;
+  try {
+    privateKey = unwrapPrivateKey(keyring.encPrivateKey, password, keyring.kdf);
+  } catch {
+    throw new Error('wrong password — could not unlock the vault');
+  }
+  // The directory must name the key we hold: a row naming another public key would let
+  // the server choose who receives what is sealed to "us".
+  if (String(keyring.publicKey || '').toLowerCase() !== publicKeyOf(privateKey)) {
+    throw new Error('the public key on file is not the one of your private key — refusing');
+  }
+  return privateKey;
+}

package/lib/crypto/aes.js

@@ -0,0 +1,35 @@
+// AES-256-GCM helper — the symmetric primitive shared by the framework's
+// zero-knowledge crypto: private-key wrap under the KDF key, secret values under
+// a DEK, and the ECIES inner cipher in keypass. Envelopes are emitted as hex so
+// they serialize cleanly into opaque `json` Vault fields.
+//
+// Isomorphic note: this uses Node's `crypto`. A browser bundle swaps this one
+// file for a WebCrypto/@noble implementation with the same { ciphertext, iv,
+// authTag } hex contract — nothing else in the lib changes.
+
+import crypto from 'crypto';
+
+const IV_BYTES = 12; // 96-bit nonce, the GCM standard
+
+// key: Buffer(32). data: Buffer. aad (optional): Buffer, authenticated, not encrypted.
+// → { ciphertext, iv, authTag } as hex strings.
+export function gcmEncrypt(key, data, aad) {
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  if (aad) cipher.setAAD(aad);
+  const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
+  return {
+    ciphertext: ciphertext.toString('hex'),
+    iv: iv.toString('hex'),
+    authTag: cipher.getAuthTag().toString('hex'),
+  };
+}
+
+// key: Buffer(32). envelope: { ciphertext, iv, authTag } hex. aad: as sealed. → Buffer.
+// Throws if the auth tag does not verify (wrong key, tampered ciphertext or other aad).
+export function gcmDecrypt(key, { ciphertext, iv, authTag }, aad) {
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'hex'));
+  if (aad) decipher.setAAD(aad);
+  decipher.setAuthTag(Buffer.from(authTag, 'hex'));
+  return Buffer.concat([decipher.update(Buffer.from(ciphertext, 'hex')), decipher.final()]);
+}

package/lib/crypto/fingerprint.js

@@ -0,0 +1,15 @@
+// A short, comparable digest of a PUBLIC key — what two people read to each other to
+// check they hold the same one. The server is the key directory, and a directory can
+// lie: clients pin the keys they have seen and show these digests when one changes.
+// SHA-256 of the key bytes, first 16 bytes, uppercase hex, grouped by 4 — every client
+// computes the same characters for the same key.
+
+import crypto from 'crypto';
+
+export function fingerprintOf(publicKeyHex) {
+  const digest = crypto
+    .createHash('sha256')
+    .update(Buffer.from(String(publicKeyHex).toLowerCase(), 'hex'))
+    .digest('hex');
+  return digest.slice(0, 32).toUpperCase().match(/.{4}/g).join(' ');
+}

package/lib/crypto/kdf.js

@@ -0,0 +1,158 @@
+// KDF + private-key wrapping. The master password is stretched with scrypt into
+// a 32-byte key that wraps (AES-256-GCM) a secp256k1 private key. Only the
+// wrapped blob + the (public) KDF params reach the server; the password and the
+// derived key never leave the client.
+//
+// Runs CLIENT-SIDE. A server storing `encPrivateKey` + `kdf` can never
+// reconstruct the key without the password.
+
+import crypto from 'crypto';
+import { promisify } from 'util';
+import { gcmEncrypt, gcmDecrypt } from './aes.js';
+
+// scrypt N=2^15 needs ~32MB; bump maxmem so Node doesn't refuse the cost.
+const SCRYPT_MAXMEM = 64 * 1024 * 1024;
+
+export function defaultKdfParams() {
+  return {
+    algo: 'scrypt',
+    salt: crypto.randomBytes(16).toString('hex'),
+    N: 32768,
+    r: 8,
+    p: 1,
+    keylen: 32,
+  };
+}
+
+// ── KDF floor — the downgrade guard ───────────────────────────────────────────
+// A client derives under params it did NOT choose: `authKdf` comes from
+// `GET /auth/prelogin`, `kdf` from the keyring row — both SERVER-supplied. Without
+// a floor, a compromised (or impersonated) server answers `{ N: 2 }`, receives a
+// verifier stretched by almost nothing, brute-forces the master password offline,
+// and then unwraps `encPrivateKey` under the REAL params. That turns "the server
+// was breached" into "every vault whose owner logged in meanwhile is plaintext" —
+// the exact event zero-knowledge exists to survive.
+//
+// So the floor is enforced where the password is stretched, not where params are
+// stored: `deriveKey` refuses anything weaker than what `defaultKdfParams` mints.
+// Raising the defaults later means raising this floor with them (older rows then
+// need a re-wrap, which is what `POST /keyring/rotate` is for).
+export const KDF_FLOOR = Object.freeze({
+  scrypt: Object.freeze({ N: 32768, r: 8, p: 1 }),
+  pbkdf2: Object.freeze({ iterations: 600000, digests: Object.freeze(['sha256', 'sha512']) }),
+  saltBytes: 16,
+  keylen: 32,
+});
+
+const isInt = (n) => Number.isInteger(n) && n > 0;
+
+// Throws on params a client must refuse to stretch a password under. Pure — also
+// used server-side to reject weak params at write time (sharedenv keyring).
+export function assertKdfParams(params) {
+  if (!params || typeof params !== 'object') throw new Error('KDF params missing');
+  const { algo = 'scrypt', salt, keylen = KDF_FLOOR.keylen } = params;
+
+  if (typeof salt !== 'string' || !/^([0-9a-fA-F]{2})+$/.test(salt)) {
+    throw new Error('KDF salt must be a hex string');
+  }
+  if (salt.length / 2 < KDF_FLOOR.saltBytes) {
+    throw new Error(`KDF salt too short (< ${KDF_FLOOR.saltBytes} bytes)`);
+  }
+  if (keylen !== KDF_FLOOR.keylen) throw new Error(`KDF keylen must be ${KDF_FLOOR.keylen}`);
+
+  if (algo === 'scrypt') {
+    const { N = KDF_FLOOR.scrypt.N, r = KDF_FLOOR.scrypt.r, p = KDF_FLOOR.scrypt.p } = params;
+    if (!isInt(N) || (N & (N - 1)) !== 0) throw new Error('scrypt N must be a power of two');
+    if (N < KDF_FLOOR.scrypt.N || !isInt(r) || r < KDF_FLOOR.scrypt.r || !isInt(p)) {
+      throw new Error('scrypt params below the accepted floor');
+    }
+    return;
+  }
+  if (algo === 'pbkdf2') {
+    const { iterations = KDF_FLOOR.pbkdf2.iterations, digest = 'sha256' } = params;
+    if (!isInt(iterations) || iterations < KDF_FLOOR.pbkdf2.iterations) {
+      throw new Error('pbkdf2 iterations below the accepted floor');
+    }
+    if (!KDF_FLOOR.pbkdf2.digests.includes(digest)) throw new Error('pbkdf2 digest not accepted');
+    return;
+  }
+  throw new Error(`Unknown KDF algo "${algo}"`);
+}
+
+// → [node:crypto function name, its arguments], shared by both flavours below.
+// Refuses params below `KDF_FLOOR` (see above) before stretching anything.
+function kdfCall(password, params) {
+  assertKdfParams(params);
+  const { algo, salt, keylen = 32 } = params;
+  const saltBuf = Buffer.from(salt, 'hex');
+
+  if (algo === 'pbkdf2') {
+    const { iterations = 600000, digest = 'sha256' } = params;
+    return ['pbkdf2', [password, saltBuf, iterations, keylen, digest]];
+  }
+
+  // default: scrypt
+  const { N = 32768, r = 8, p = 1 } = params;
+  return ['scrypt', [password, saltBuf, keylen, { N, r, p, maxmem: SCRYPT_MAXMEM }]];
+}
+
+const ASYNC_KDF = { pbkdf2: promisify(crypto.pbkdf2), scrypt: promisify(crypto.scrypt) };
+
+// password: string. params: { algo, salt(hex), ... }. → Buffer(keylen).
+// SYNC: ~75 ms of the calling thread. Fine for a CLI or a test; a server on a
+// request path takes `deriveKeyAsync`.
+export function deriveKey(password, params) {
+  const [algo, args] = kdfCall(password, params);
+  return algo === 'pbkdf2' ? crypto.pbkdf2Sync(...args) : crypto.scryptSync(...args);
+}
+
+// The same key, derived on the libuv pool: the event loop keeps serving the
+// process's other requests meanwhile.
+export async function deriveKeyAsync(password, params) {
+  const [algo, args] = kdfCall(password, params);
+  return ASYNC_KDF[algo](...args);
+}
+
+// ── Login verifier ────────────────────────────────────────────────────────────
+// Never the raw scrypt output: that is what a wrap key is made of, and `authKdf` is
+// chosen by the server (GET /auth/prelogin) — a compromised server could serve the
+// keyring's `kdf` as `authKdf` and receive the wrap key as the "verifier".
+// HMAC-SHA256 keyed by scrypt(password, authKdf), over AUTH_VERIFIER_LABEL: every
+// client derives the same bytes.
+export const AUTH_VERIFIER_LABEL = 'sharedenv/auth-verifier/v2';
+
+// Login params a client mints.
+export function defaultAuthKdfParams() {
+  return { ...defaultKdfParams(), v: 2 };
+}
+
+// → the verifier a client sends for `params` as prelogin serves them. Async: scrypt
+// on the libuv pool.
+export async function deriveAuthVerifier(password, params) {
+  const stretched = await deriveKeyAsync(password, params);
+  return crypto.createHmac('sha256', stretched).update(AUTH_VERIFIER_LABEL).digest('hex');
+}
+
+// privateKeyHex: string. password: string. params: optional KDF params.
+// → { encPrivateKey: { ciphertext, iv, authTag }, kdf: params }.
+export function wrapPrivateKey(privateKeyHex, password, params = defaultKdfParams()) {
+  const key = deriveKey(password, params);
+  const encPrivateKey = gcmEncrypt(key, Buffer.from(privateKeyHex, 'utf8'));
+  return { encPrivateKey, kdf: params };
+}
+
+// → privateKeyHex string. Throws if the password is wrong (GCM tag fails).
+export function unwrapPrivateKey(encPrivateKey, password, kdf) {
+  const key = deriveKey(password, kdf);
+  return gcmDecrypt(key, encPrivateKey).toString('utf8');
+}
+
+// A one-time recovery code shown to the user once, at keyring creation. It is a
+// SECOND passphrase the private key is wrapped under (`wrapPrivateKey(pk, code)`)
+// so a forgotten password no longer orphans the vault: after a password reset,
+// the client unwraps with this code and re-wraps under the new password. Runs
+// CLIENT-SIDE; the server never sees it. 160 bits, grouped for transcription.
+export function generateRecoveryCode() {
+  const hex = crypto.randomBytes(20).toString('hex').toUpperCase(); // 40 chars
+  return hex.match(/.{5}/g).join('-'); // 8 groups of 5
+}

package/lib/crypto/keypass.js

@@ -0,0 +1,129 @@
+// Keypass — secp256k1 primitives (@noble/curves): key pairs, ECDSA sign/verify, and the
+// authenticated box Wallet builds on (ECDH shared secret → SHA-256 → AES-256-GCM, with a
+// 65-byte signature appended to the payload). The signature proves who sealed the
+// message; the GCM tag proves it was not altered.
+//
+// The byte format is shared by every client (Node, browser, extension):
+//   - private key: hex, 32 bytes. Keys minted by older clients may have dropped their
+//     leading zeros, so input is padded before use.
+//   - public key: compressed point (33 bytes), hex.
+//   - signed digest: SHA-256 of JSON.stringify(message). For a Buffer that is the UTF-8
+//     of {"type":"Buffer","data":[...]} — odd, but every sealed envelope carries it.
+//   - signature: r(32) || s(32) || recovery(1), deterministic (RFC 6979), low-S when
+//     signed here. Verification accepts both halves of s: envelopes sealed by older
+//     clients carry high-S signatures.
+//
+// The private-key operations (keyPair, sign, the ECDH of encrypt/decrypt) run CLIENT-SIDE;
+// a zero-knowledge server only ever calls `verify`.
+
+import crypto from 'crypto';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+
+const SIG_BYTES = 65; // r(32) + s(32) + recovery(1)
+
+// hex (possibly unpadded) → the 32 bytes of a private key.
+export function privateKeyBytes(privateKeyHex) {
+  const hex = String(privateKeyHex);
+  if (!/^[0-9a-fA-F]{1,64}$/.test(hex)) throw new Error('A private key is up to 64 hex characters');
+  return Buffer.from(hex.padStart(64, '0'), 'hex');
+}
+
+function digest(message) {
+  return crypto.createHash('sha256').update(JSON.stringify(message)).digest();
+}
+
+const hex64 = (n) => n.toString(16).padStart(64, '0');
+
+// r or s as a bigint, a hex string or a bn.js-like value → 64 hex characters.
+function scalarHex(value) {
+  const hex = typeof value === 'string' ? value : value.toString(16);
+  if (!/^[0-9a-fA-F]{1,64}$/.test(hex)) throw new Error('Malformed signature scalar');
+  return hex.padStart(64, '0');
+}
+
+export class Keypass {
+  keyPair() {
+    const secretKey = secp256k1.utils.randomSecretKey();
+    return {
+      privateKey: Buffer.from(secretKey).toString('hex'),
+      publicKey: Buffer.from(secp256k1.getPublicKey(secretKey, true)).toString('hex'),
+    };
+  }
+
+  publicFromPrivate(privateKey) {
+    return Buffer.from(secp256k1.getPublicKey(privateKeyBytes(privateKey), true)).toString('hex');
+  }
+
+  // → { r, s, recoveryParam }, r and s as bigints.
+  sign(privateKey, message) {
+    const sig = secp256k1.sign(digest(message), privateKeyBytes(privateKey), {
+      prehash: false, // the digest is already SHA-256: sign it as is
+      format: 'recovered', // recovery(1) || r(32) || s(32)
+    });
+    const hex = Buffer.from(sig).toString('hex');
+    return {
+      r: BigInt(`0x${hex.slice(2, 66)}`),
+      s: BigInt(`0x${hex.slice(66, 130)}`),
+      recoveryParam: sig[0],
+    };
+  }
+
+  // signature: { r, s } (bigints or hex). → boolean, never throws.
+  verify(publicKey, message, signature) {
+    try {
+      const rs = Buffer.from(scalarHex(signature.r) + scalarHex(signature.s), 'hex');
+      return secp256k1.verify(rs, digest(message), Buffer.from(publicKey, 'hex'), {
+        prehash: false,
+        lowS: false,
+      });
+    } catch {
+      return false;
+    }
+  }
+
+  // senderPrivateKey, recipientPublicKey: hex. packet: { signature, payload: Buffer }.
+  // → { encrypted, iv, authTag } as Buffers.
+  encrypt(senderPrivateKey, recipientPublicKey, { signature, payload }) {
+    const sigBuffer = Buffer.concat([
+      Buffer.from(hex64(signature.r) + hex64(signature.s), 'hex'),
+      Buffer.from([signature.recoveryParam || 0]),
+    ]);
+    const messageBuffer = Buffer.concat([payload, sigBuffer]);
+
+    const encryptionKey = this.#sharedKey(senderPrivateKey, recipientPublicKey);
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', encryptionKey, iv);
+    const encrypted = Buffer.concat([cipher.update(messageBuffer), cipher.final()]);
+
+    return { encrypted, iv, authTag: cipher.getAuthTag() };
+  }
+
+  // recipientPrivateKey, senderPublicKey: hex. encryptedData: { encrypted, iv, authTag } Buffers.
+  // → { payload: Buffer, signature } — throws if the GCM tag fails (altered or wrong key).
+  decrypt(recipientPrivateKey, senderPublicKey, { encrypted, iv, authTag }) {
+    const decryptionKey = this.#sharedKey(recipientPrivateKey, senderPublicKey);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', decryptionKey, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+
+    const payload = decrypted.subarray(0, decrypted.length - SIG_BYTES);
+    const sigHex = decrypted.subarray(decrypted.length - SIG_BYTES).toString('hex');
+    const signature = {
+      r: BigInt(`0x${sigHex.slice(0, 64)}`),
+      s: BigInt(`0x${sigHex.slice(64, 128)}`),
+      recoveryParam: parseInt(sigHex.slice(128, 130), 16),
+    };
+
+    return { payload, signature };
+  }
+
+  // ECDH shared secret (its X coordinate) → SHA-256 → 32-byte symmetric key.
+  #sharedKey(privateKey, publicKey) {
+    const point = secp256k1.getSharedSecret(
+      privateKeyBytes(privateKey),
+      Buffer.from(publicKey, 'hex'),
+      true
+    );
+    return crypto.createHash('sha256').update(point.subarray(1)).digest();
+  }
+}

package/lib/crypto/secretBlob.js

@@ -0,0 +1,49 @@
+// Secret blobs of the zero-knowledge vault — every client (Node, browser) writes and reads
+// the same bytes.
+//
+//   { v: 2, ciphertext, iv, authTag, ctx } — ctx = { safeId, key, kind } is the secret's
+//   place, authenticated as AES-GCM additional data. A reader that knows where it found the
+//   blob compares and refuses a stranger; without that, the blob is read at the place it
+//   names. Any other shape is refused: a ciphertext with no place would be valid wherever a
+//   server put it (two values of a safe swapped, a sealed meta served as a value).
+
+import { gcmDecrypt, gcmEncrypt } from './aes.js';
+
+const LABELS = { value: 'sharedenv/secret/v2', meta: 'sharedenv/meta/v2' };
+
+// → the canonical ctx. Throws on anything but { safeId, key, kind? }.
+function placeOf(ctx) {
+  const kind = ctx?.kind || 'value';
+  if (!LABELS[kind] || ctx?.safeId == null || ctx?.key == null) {
+    throw new Error('A secret context is { safeId, key, kind: value|meta }');
+  }
+  return { safeId: String(ctx.safeId), key: String(ctx.key), kind };
+}
+
+const aadOf = (place) =>
+  Buffer.from([LABELS[place.kind], place.safeId, place.key].join('\u0000'), 'utf8');
+
+// dekHex, plaintext: strings. ctx: the place the blob is bound to. → a v2 blob.
+export function sealSecret(dekHex, plaintext, ctx) {
+  const place = placeOf(ctx);
+  const blob = gcmEncrypt(
+    Buffer.from(dekHex, 'hex'),
+    Buffer.from(String(plaintext), 'utf8'),
+    aadOf(place)
+  );
+  return { v: 2, ...blob, ctx: place };
+}
+
+// → plaintext. `expected` (optional): where the caller found the blob — a blob from
+// anywhere else is refused. Throws when no key opens it (AES-GCM authenticates).
+export function openSecret(dekHex, blob, expected) {
+  if (blob?.v !== 2) throw new Error('Not a secret blob: { v: 2, ..., ctx } expected');
+  const place = placeOf(blob.ctx);
+  if (expected) {
+    const want = placeOf(expected);
+    if (want.safeId !== place.safeId || want.key !== place.key || want.kind !== place.kind) {
+      throw new Error(`This blob belongs to ${place.kind} "${place.key}" of safe ${place.safeId}`);
+    }
+  }
+  return gcmDecrypt(Buffer.from(dekHex, 'hex'), blob, aadOf(place)).toString('utf8');
+}

package/lib/crypto/wallet.js

@@ -0,0 +1,63 @@
+// Wallet — the seal/open layer on top of Keypass. `seal`/`open` exchange a
+// self-contained, JSON-serializable hex envelope { ciphertext, iv, authTag,
+// senderPublicKey } that drops straight into opaque `json` Vault fields. `open`
+// returns `false` (never throws) on any tamper or wrong key.
+
+import { Keypass } from './keypass.js';
+
+export class Wallet {
+  constructor() {
+    this.keypass = new Keypass();
+  }
+
+  create() {
+    return this.keypass.keyPair();
+  }
+
+  // senderPrivateKey, recipientPublicKey: hex. payload: Buffer.
+  // → { ciphertext, iv, authTag, senderPublicKey } as hex strings.
+  seal(senderPrivateKey, recipientPublicKey, payload) {
+    const signature = this.keypass.sign(senderPrivateKey, payload);
+    const { encrypted, iv, authTag } = this.keypass.encrypt(senderPrivateKey, recipientPublicKey, {
+      payload,
+      signature,
+    });
+    return {
+      ciphertext: encrypted.toString('hex'),
+      iv: iv.toString('hex'),
+      authTag: authTag.toString('hex'),
+      senderPublicKey: this.keypass.publicFromPrivate(senderPrivateKey),
+    };
+  }
+
+  // recipientPrivateKey: hex. envelope: { ciphertext, iv, authTag, senderPublicKey }.
+  // → payload Buffer, or `false` if decryption or signature verification fails.
+  //
+  // The signature only proves the envelope was sealed by the key it NAMES itself, and
+  // any key can seal a payload of its choosing to ours. `from` (a public key, or a
+  // list) is the sender the caller expects: an envelope from anyone else is refused
+  // like a tampered one. Every client implements the same contract.
+  open(recipientPrivateKey, envelope, { from } = {}) {
+    const { ciphertext, iv, authTag, senderPublicKey } = envelope;
+    if (from) {
+      const expected = (Array.isArray(from) ? from : [from]).map((k) => String(k).toLowerCase());
+      if (!expected.includes(String(senderPublicKey).toLowerCase())) return false;
+    }
+    let decrypted;
+    try {
+      decrypted = this.keypass.decrypt(recipientPrivateKey, senderPublicKey, {
+        encrypted: Buffer.from(ciphertext, 'hex'),
+        iv: Buffer.from(iv, 'hex'),
+        authTag: Buffer.from(authTag, 'hex'),
+      });
+    } catch {
+      return false; // GCM tag failed → ciphertext or key tampered
+    }
+
+    const { payload, signature } = decrypted;
+    if (!this.keypass.verify(senderPublicKey, payload, signature)) {
+      return false; // signature does not match the claimed sender
+    }
+    return payload;
+  }
+}

package/lib/crypto.js

@@ -0,0 +1,10 @@
+// The crypto the CLI uses: copies of the framework files, under ./crypto.
+
+export { Wallet } from './crypto/wallet.js';
+export {
+  assertKdfParams,
+  deriveAuthVerifier,
+  unwrapPrivateKey,
+} from './crypto/kdf.js';
+export { openSecret } from './crypto/secretBlob.js';
+export { fingerprintOf } from './crypto/fingerprint.js';

package/lib/env.js

@@ -0,0 +1,96 @@
+// The environment `sharedenv run` gives the child process.
+//
+// A safe is writable by every WRITER on it. Injected blindly, its values would make write
+// access to a shared safe code execution — or eavesdropping — on the machine of whoever
+// runs it next (a teammate's laptop, the CI runner). Two rules:
+//
+//   - names that make the dynamic loader, a shell, an interpreter or a tool the child
+//     spawns run code of someone else's choosing, or route and trust its traffic
+//     (UNSAFE_ENV), are held back unless `--allow-unsafe-env`;
+//   - no such list is complete, so a name the caller's environment already sets is not
+//     overridden either, unless `--override-env`.
+//
+// And the child never receives the CLI's own SHAREDENV_* variables: SHAREDENV_PASSWORD
+// opens every safe of the account, not just the one being run.
+
+const UNSAFE_ENV = [
+  // dynamic loader, shells
+  /^LD_/,
+  /^DYLD_/,
+  /^PATH$/,
+  /^IFS$/,
+  /^BASH_ENV$/,
+  /^BASH_FUNC_/,
+  /^ENV$/,
+  /^SHELLOPTS$/,
+  /^BASHOPTS$/,
+  /^PS4$/,
+  /^PROMPT_COMMAND$/,
+  /^ZDOTDIR$/,
+  // interpreters
+  /^NODE_OPTIONS$/,
+  /^NODE_PATH$/,
+  /^NODE_REPL_EXTERNAL_MODULE$/,
+  /^PYTHONSTARTUP$/,
+  /^PYTHONPATH$/,
+  /^PYTHONHOME$/,
+  /^PYTHONINSPECT$/,
+  /^PERL5OPT$/,
+  /^PERL5LIB$/,
+  /^PERLLIB$/,
+  /^RUBYOPT$/,
+  /^RUBYLIB$/,
+  /^JAVA_TOOL_OPTIONS$/,
+  /^_JAVA_OPTIONS$/,
+  /^JDK_JAVA_OPTIONS$/,
+  // tools the child may spawn
+  /^GIT_/,
+  /^NPM_CONFIG_/,
+  /^YARN_/,
+  /^COMPOSER_/,
+  /^PAGER$/,
+  /^MANPAGER$/,
+  /^LESSOPEN$/,
+  /^LESSCLOSE$/,
+  /^EDITOR$/,
+  /^VISUAL$/,
+  /^BROWSER$/,
+  /^SSH_ASKPASS$/,
+  /^SUDO_ASKPASS$/,
+  // where the child's traffic goes, and which certificates it trusts: together they let
+  // a writer read the other secrets in flight
+  /^(HTTPS?|ALL|FTP)_PROXY$/,
+  /^NODE_EXTRA_CA_CERTS$/,
+  /^NODE_TLS_REJECT_UNAUTHORIZED$/,
+  /^SSL_CERT_(FILE|DIR)$/,
+  /_CA_BUNDLE$/,
+  // this CLI's own configuration (a nested `sharedenv` would talk to another server)
+  /^SHAREDENV_/,
+];
+
+const OWN_ENV = /^SHAREDENV_/i;
+
+// → { safe: {…}, blocked: [names], kept: [names] }. Matched case-insensitively.
+//   blocked — UNSAFE_ENV names, unless `allowUnsafe`;
+//   kept    — names `base` (the caller's environment) already sets: its value stays,
+//             unless `override`.
+export function splitUnsafeEnv(map, { base = {}, allowUnsafe = false, override = false } = {}) {
+  const safe = {};
+  const blocked = [];
+  const kept = [];
+  for (const [name, value] of Object.entries(map)) {
+    if (!allowUnsafe && UNSAFE_ENV.some((re) => re.test(name.toUpperCase()))) blocked.push(name);
+    else if (!override && Object.hasOwn(base, name)) kept.push(name);
+    else safe[name] = value;
+  }
+  return { safe, blocked, kept };
+}
+
+// The child's environment: the caller's, minus SHAREDENV_*, plus the injected secrets.
+export function childEnv(parentEnv, injected) {
+  const env = {};
+  for (const [name, value] of Object.entries(parentEnv)) {
+    if (!OWN_ENV.test(name)) env[name] = value;
+  }
+  return { ...env, ...injected };
+}

package/lib/format.js

@@ -0,0 +1,42 @@
+// What `sharedenv pull` writes. Keys are sorted, so two pulls of the same safe give the
+// same file.
+//
+// A .env is read by dotenv-style parsers AND sourced by shells (`set -a; . ./.env`).
+// Each value is written in the first form both read literally — nothing expanded,
+// nothing executed: a value is chosen by any WRITER on the safe, and `$(…)` in double
+// quotes would run on the machine that sources the file.
+//
+//   bare     only characters with no meaning to either
+//   '…'      anything without a single quote (newlines included)
+//   "…"      a single quote, but none of " $ ` \ (which a shell or dotenv would interpret)
+//
+// A value that fits none (or holds a carriage return, which dotenv rewrites) is refused
+// with its name: `--format json` or `sharedenv run` carry it as is.
+
+const BARE = /^[A-Za-z0-9_\-.,:/@+%]+$/;
+
+const sorted = (map) => Object.entries(map).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+
+function dotenvValue(name, value) {
+  if (BARE.test(value)) return value;
+  if (!value.includes('\r')) {
+    if (!value.includes("'")) return `'${value}'`;
+    if (!/["$`\\]/.test(value)) return `"${value}"`;
+  }
+  throw new Error(
+    `"${name}" cannot be written as a .env line that is safe to source (it holds a ' with ` +
+      'one of " $ ` \\, or a carriage return): use --format json, or sharedenv run'
+  );
+}
+
+export function toDotenv(map) {
+  return sorted(map)
+    .map(([name, value]) => `${name}=${dotenvValue(name, value)}`)
+    .join('\n');
+}
+
+export function toJson(map) {
+  return JSON.stringify(Object.fromEntries(sorted(map)), null, 2);
+}
+
+export const FORMATS = { dotenv: toDotenv, json: toJson };