@sharedenv/cli 0.0.0-stage → 1.0.0

package/lib/run.js

@@ -0,0 +1,41 @@
+// Runs the child of `sharedenv run` and reports how it ended, the way a shell would: its
+// exit code, or 128 + n when signal n ended it (a CI must not read an OOM kill as a
+// success). The signals the CLI receives are passed on, so stopping the CLI (`docker
+// stop`, Ctrl-C, a closed terminal) stops the child instead of orphaning it.
+
+import { spawn } from 'child_process';
+import { constants } from 'os';
+
+const FORWARDED = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+// A command that could not start, with the exit code a shell gives it.
+const UNSTARTABLE = {
+  ENOENT: ['command not found', 127],
+  EACCES: ['permission denied', 126],
+};
+
+function spawnError(command, err) {
+  if (!UNSTARTABLE[err.code]) return err;
+  const [what, exitCode] = UNSTARTABLE[err.code];
+  return Object.assign(new Error(`${what}: ${command}`), { exitCode });
+}
+
+// → Promise<exit code>. Rejects (with `exitCode`) when the command cannot be started.
+export function runChild(command, args, env, { stdio = 'inherit' } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio, env });
+    const forward = (signal) => child.kill(signal);
+    let settled = false;
+    const settle = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      for (const signal of FORWARDED) process.off(signal, forward);
+      fn(value);
+    };
+    for (const signal of FORWARDED) process.on(signal, forward);
+    child.on('error', (err) => settle(reject, spawnError(command, err)));
+    child.on('exit', (code, signal) =>
+      settle(resolve, signal ? 128 + (constants.signals[signal] ?? 0) : code ?? 0)
+    );
+  });
+}

package/lib/safes.js

@@ -0,0 +1,106 @@
+// Reading a safe: find it, recover its key (DEK), decrypt every secret — locally. The
+// server only ever returns ciphertext.
+
+import { Wallet, openSecret } from './crypto.js';
+import { expectOk, listAll } from './api.js';
+import { PendingShareError, listPendingShares } from './shares.js';
+
+const wallet = new Wallet();
+const SAFE_ID = /^[a-f0-9]{24}$/i;
+
+// Secret names the API accepts. Checked again here: the server is the party
+// zero-knowledge does not trust, and a name lands in a .env line or an environment.
+const SECRET_NAME = /^[A-Za-z0-9_-]+$/;
+
+// A safe by id, or by (case-insensitive) name. A share still waiting for the caller's
+// answer is not in their list: it is named as such rather than reported missing.
+export async function resolveSafe(client, ref) {
+  if (SAFE_ID.test(ref)) return ref;
+  const name = ref.toLowerCase();
+  const safes = await listAll(client, '/safes', 'safes');
+  const match = safes.find((s) => s.name?.toLowerCase() === name);
+  if (match) return String(match._id);
+  const pending = (await listPendingShares(client)).direct.find(
+    (p) => p.safe?.name?.toLowerCase() === name
+  );
+  if (pending) throw new PendingShareError(pending);
+  throw new Error(`no vault named "${ref}"`);
+}
+
+// Every DEK the caller's paths to a safe yield, CURRENT first: a direct envelope, or a
+// team grant (own key → team key → DEK). More than one only while a key rotation is in
+// flight: each row then also carries the blob it held before (`previous…`), and secrets
+// may sit under either key.
+export function resolveDeks(privateKey, safe) {
+  const deks = [];
+  const add = (opened) => {
+    const hex = opened ? opened.toString('hex') : null;
+    if (hex && !deks.includes(hex)) deks.push(hex);
+  };
+  const m = safe.membership;
+  for (const blob of [m?.sealedSafeKey, m?.previousSealedSafeKey]) {
+    if (blob) add(wallet.open(privateKey, blob));
+  }
+  for (const grant of safe.teamAccess || []) {
+    const teamKeys = [grant.sealedTeamKey, grant.previousSealedTeamKey]
+      .filter(Boolean)
+      .map((blob) => wallet.open(privateKey, blob))
+      .filter(Boolean)
+      .map((opened) => opened.toString('utf8'));
+    for (const blob of [grant.sealedSafeKey, grant.previousSealedSafeKey]) {
+      if (!blob) continue;
+      const opened = teamKeys.map((teamKey) => wallet.open(teamKey, blob)).find(Boolean);
+      if (opened) add(opened);
+    }
+  }
+  return deks;
+}
+
+// AES-GCM authenticates: the first key that opens a value is the one it was written
+// under. `place` is where the value was read: a blob moved there from another secret or
+// another safe is refused.
+function decryptWithAny(deks, blob, place) {
+  let misplaced = null;
+  for (const dek of deks) {
+    try {
+      return openSecret(dek, blob, place);
+    } catch (err) {
+      if (/belongs to/.test(err.message)) misplaced = err;
+    }
+  }
+  if (misplaced) throw new Error(`refusing "${place.key}": ${misplaced.message}`);
+  throw new Error(
+    `cannot decrypt "${place.key}" — a key rotation may be in progress, retry shortly`
+  );
+}
+
+// → { KEY: value } — every secret of the safe, decrypted. All or nothing: one value that
+// cannot be read fails the pull, so `run` never starts a process with a variable missing.
+export async function pullSecrets(client, privateKey, safeId) {
+  const res = await client.call('GET', `/safes/${safeId}`);
+  if (res.status === 403 && res.body?.key === 'sharePending') {
+    const pending = (await listPendingShares(client)).direct.find(
+      (p) => String(p.safeId) === String(safeId)
+    );
+    throw pending
+      ? new PendingShareError(pending)
+      : new Error('this vault is shared with you but waits for your answer: run `sharedenv list`');
+  }
+  const safe = expectOk(res, 'cannot open the vault');
+
+  const deks = resolveDeks(privateKey, safe);
+  if (deks.length === 0) {
+    throw new Error('no key to this vault on your account (not a member, or not provisioned yet)');
+  }
+
+  const secrets = {};
+  for (const row of await listAll(client, `/secrets/${safeId}`, 'secrets')) {
+    if (typeof row.key !== 'string' || !SECRET_NAME.test(row.key)) {
+      throw new Error(`refusing a secret named ${JSON.stringify(row.key)}: not a variable name`);
+    }
+    if (Object.hasOwn(secrets, row.key))
+      throw new Error(`the server sent "${row.key}" twice for this vault`);
+    secrets[row.key] = decryptWithAny(deks, row.ciphertextValue, { safeId, key: row.key });
+  }
+  return secrets;
+}

package/lib/shares.js

@@ -0,0 +1,169 @@
+// Shares received. A share someone sends waits for its recipient: until accepted it
+// opens nothing. To accept, the envelope is opened with the SENDER's directory key —
+// `open(…, { from })` — never with the key the envelope names itself (any key can seal
+// a DEK to ours): a share not sealed by the person it claims to come from is refused.
+
+import { Wallet, fingerprintOf } from './crypto.js';
+import { expectOk, listAll } from './api.js';
+
+const wallet = new Wallet();
+
+export class PendingShareError extends Error {
+  constructor(share) {
+    super(
+      `"${share.safe?.name || share.safeId}" is a share from ${senderLabel(share)} waiting for ` +
+        `your answer: run \`sharedenv list\` to review it, then \`sharedenv accept ` +
+        `${share.safeId}\` (or \`decline\`)`
+    );
+    this.code = 'SHARE_PENDING';
+    this.share = share;
+  }
+}
+
+export function senderLabel(share) {
+  const from = share?.from || {};
+  const name = [from.firstName, from.lastName].filter(Boolean).join(' ').trim();
+  if (!from.username) return String(from._id || 'unknown');
+  return name ? `${name} (${from.username})` : from.username;
+}
+
+// → { direct: [...], team: [...] }. Each row carries `from` (name + directory key) and
+// `fingerprint`, computed here from that key, never taken from the server.
+export async function listPendingShares(client) {
+  const withFingerprint = (rows) =>
+    rows.map((row) => ({
+      ...row,
+      fingerprint: row.from?.publicKey ? fingerprintOf(row.from.publicKey) : null,
+    }));
+  const direct = await listAll(client, '/shares', 'pending shares');
+  const team = await listAll(client, '/team-shares', 'pending team shares');
+  return { direct: withFingerprint(direct), team: withFingerprint(team) };
+}
+
+// A pending share by safe id, or by the name of its safe (`teamId`: among the shares to
+// that team). → the safe id.
+export async function resolvePendingShare(client, ref, teamId) {
+  if (/^[a-f0-9]{24}$/i.test(ref)) return ref;
+  const { direct, team } = await listPendingShares(client);
+  const rows = teamId ? team.filter((p) => String(p.teamId) === String(teamId)) : direct;
+  const match = rows.find((p) => p.safe?.name?.toLowerCase() === ref.toLowerCase());
+  if (!match) throw new Error(`no pending share named "${ref}"${teamId ? ' for this team' : ''}`);
+  return String(match.safeId);
+}
+
+function senderKeyOf(share) {
+  const key = share?.from?.publicKey;
+  if (!key) {
+    throw new Error(
+      `${senderLabel(share)} has no key on file any more (keyring reset?): ask them to share again, or decline`
+    );
+  }
+  return String(key).toLowerCase();
+}
+
+// → { share, senderKey, fingerprint }; throws when the seal is not the sender's.
+export async function openPendingShare(client, privateKey, safeId) {
+  const { share } = expectOk(await client.call('GET', `/shares/${safeId}`), 'no pending share');
+  const senderKey = senderKeyOf(share);
+  if (!wallet.open(privateKey, share.sealedSafeKey, { from: senderKey })) {
+    throw new Error(
+      `this share was NOT sealed by ${senderLabel(share)} (key ${fingerprintOf(senderKey)}): decline it`
+    );
+  }
+  return { share, senderKey, fingerprint: fingerprintOf(senderKey) };
+}
+
+// Check, then accept. `confirm(opened)` (async → boolean) is where a human compares the
+// fingerprint; a no leaves the share pending.
+export async function acceptShare(client, privateKey, safeId, { confirm } = {}) {
+  const opened = await openPendingShare(client, privateKey, safeId);
+  if (confirm && !(await confirm(opened))) return { ...opened, accepted: false };
+  expectOk(await client.call('POST', `/shares/${safeId}/accept`), 'cannot accept the share');
+  return { ...opened, accepted: true };
+}
+
+export async function declineShare(client, safeId) {
+  expectOk(await client.call('POST', `/shares/${safeId}/decline`), 'cannot decline the share');
+  return true;
+}
+
+// A pending TEAM grant, opened by someone who answers for the team and holds its key:
+// own key → team key (current, or the previous one: a team-key rotation leaves pending
+// grants where they are) → DEK, checked against the sender's key.
+//
+// → { share, dek, senderKey, fingerprint, teamPublicKey, teamKeyVouched }, where
+// `teamPublicKey` is the team's CURRENT key, derived from the private key we hold.
+// Holding it proves nothing on its own (any key can seal a team key to ours, and the
+// keyring row is the server's): `teamKeyVouched` is false when the DEK opened with the
+// PREVIOUS key and the current one was not sealed by us — the caller must then check
+// it before the DEK moves to it (acceptTeamShare).
+export async function openPendingTeamShare(client, privateKey, teamId, safeId) {
+  const { share } = expectOk(
+    await client.call('GET', `/team-shares/${teamId}/${safeId}`),
+    'no pending team share'
+  );
+  const senderKey = senderKeyOf(share);
+  const current = share.sealedTeamKey && wallet.open(privateKey, share.sealedTeamKey);
+  if (!current) throw new Error('cannot open your team key for this team');
+  const previous =
+    share.previousSealedTeamKey && wallet.open(privateKey, share.previousSealedTeamKey);
+  const teamKeys = [current, previous].filter(Boolean).map((key) => key.toString('utf8'));
+
+  let dek = false;
+  let openedWith = -1;
+  for (const [i, teamKey] of teamKeys.entries()) {
+    dek = wallet.open(teamKey, share.sealedSafeKey, { from: senderKey });
+    if (dek) {
+      openedWith = i;
+      break;
+    }
+  }
+  if (!dek) {
+    const opensAnyway = teamKeys.some((key) => wallet.open(key, share.sealedSafeKey));
+    throw new Error(
+      opensAnyway
+        ? `this share was NOT sealed by ${senderLabel(share)} (key ${fingerprintOf(senderKey)}): decline it`
+        : 'this share is sealed to a team key replaced since: ask the sender to share it again, or decline'
+    );
+  }
+  const ownKey = wallet.keypass.publicFromPrivate(privateKey);
+  return {
+    share,
+    dek,
+    senderKey,
+    fingerprint: fingerprintOf(senderKey),
+    teamPublicKey: wallet.keypass.publicFromPrivate(teamKeys[0]),
+    teamKeyVouched:
+      openedWith === 0 || Boolean(wallet.open(privateKey, share.sealedTeamKey, { from: ownKey })),
+  };
+}
+
+// Check, re-seal to the team's current key (by us), accept. The grant version we opened
+// travels with it: a rotation in between makes it a 409, never an old DEK.
+export async function acceptTeamShare(client, privateKey, teamId, safeId, { confirm } = {}) {
+  const opened = await openPendingTeamShare(client, privateKey, teamId, safeId);
+  // The DEK never moves to a team key nobody vouched for: `confirm` must check it.
+  if (!opened.teamKeyVouched && !confirm) {
+    throw new Error(
+      'the current team key is not vouched for on this machine: accept interactively'
+    );
+  }
+  if (confirm && !(await confirm(opened))) return { ...opened, accepted: false };
+  const sealedSafeKey = wallet.seal(privateKey, opened.teamPublicKey, opened.dek);
+  expectOk(
+    await client.call('POST', `/team-shares/${teamId}/${safeId}/accept`, {
+      sealedSafeKey: JSON.stringify(sealedSafeKey),
+      keyVersion: opened.share.keyVersion,
+    }),
+    'cannot accept the team share'
+  );
+  return { ...opened, accepted: true };
+}
+
+export async function declineTeamShare(client, teamId, safeId) {
+  expectOk(
+    await client.call('POST', `/team-shares/${teamId}/${safeId}/decline`),
+    'cannot decline the team share'
+  );
+  return true;
+}

package/lib/store.js

@@ -0,0 +1,66 @@
+// What the CLI keeps on disk, under ~/.sharedenv (or $SHAREDENV_HOME): the session
+// cookies, and the public keys this machine has vouched for (trust.js). Never the
+// password, never a private key, never a secret.
+
+import { randomBytes } from 'crypto';
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeSync,
+} from 'fs';
+import { homedir } from 'os';
+import { basename, dirname, join } from 'path';
+
+// Writes `data` to `file`, readable by its owner only. Through a fresh temporary file
+// then a rename: the target is never readable by others, not even for an instant (an
+// existing .env is often 0644), a symlink planted at its path is replaced rather than
+// followed, and a crash never leaves half a file.
+export function writePrivate(file, data) {
+  const tmp = join(dirname(file), `.${basename(file)}.${randomBytes(6).toString('hex')}.tmp`);
+  const fd = openSync(tmp, 'wx', 0o600);
+  try {
+    writeSync(fd, data);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    renameSync(tmp, file);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function createStore(dir = process.env.SHAREDENV_HOME || join(homedir(), '.sharedenv')) {
+  const sessionFile = join(dir, 'session.json');
+  const pinsFile = join(dir, 'pins.json');
+  const save = (file, value) => {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writePrivate(file, `${JSON.stringify(value, null, 2)}\n`);
+  };
+
+  return {
+    dir,
+    // → { baseUrl, cookies } | null
+    readSession: () => readJson(sessionFile),
+    writeSession: (session) => save(sessionFile, session),
+    clearSession: () => rmSync(sessionFile, { force: true }),
+    // → { [subject]: publicKey }
+    readPins: () => readJson(pinsFile) || {},
+    writePins: (pins) => save(pinsFile, pins),
+  };
+}

package/lib/trust.js

@@ -0,0 +1,45 @@
+// Whose keys this machine believes. The server is the key directory, and a directory
+// can lie; a key legitimately changes in one case only (its owner reset their keyring,
+// or a team rotated its key) — exactly the event a lying server would fake. So:
+//
+//   - trust on first use: the first key seen for someone (`user:<id>`, `team:<id>`) is
+//     pinned on this machine (~/.sharedenv/pins.json), and a DIFFERENT key later is
+//     never taken silently;
+//   - a fingerprint given on the command line (checked with its owner over another
+//     channel) settles the question for scripts, instead of a blind yes.
+//
+// Pure functions: the bin asks the questions and persists the pins.
+
+// → 'new' (never seen here) | 'match' | 'changed'
+export function pinStatus(pins, subject, publicKey) {
+  const pinned = pins?.[subject];
+  if (!pinned) return 'new';
+  return pinned === String(publicKey).toLowerCase() ? 'match' : 'changed';
+}
+
+export function pinKey(pins, subject, publicKey) {
+  pins[subject] = String(publicKey).toLowerCase();
+  return pins;
+}
+
+const normalized = (fingerprint) => String(fingerprint).replace(/\s+/g, '').toUpperCase();
+
+export const sameFingerprint = (a, b) => normalized(a) === normalized(b);
+
+// The sender of a share. → 'accept' | 'ask' | 'refuse'
+//   expected         — `--fingerprint`: the key must be this one, nothing else counts;
+//   acceptKeyChange  — `--accept-key-change`: take a key that differs from the pin;
+//   yes              — `--yes`: no question for a key that is new or already pinned.
+export function senderVerdict(status, fingerprint, { expected, acceptKeyChange, yes } = {}) {
+  if (expected) return sameFingerprint(expected, fingerprint) ? 'accept' : 'refuse';
+  if (status === 'changed') return acceptKeyChange ? 'accept' : 'ask';
+  return yes ? 'accept' : 'ask';
+}
+
+// The team key a share moves to on accept, when no seal of ours vouches for it: a planted
+// key would receive the safe's key. Pinned, or confirmed by its fingerprint — by a human
+// or by `--team-fingerprint` — and no flag says yes blindly. → 'accept' | 'ask' | 'refuse'
+export function teamKeyVerdict(status, fingerprint, { expected } = {}) {
+  if (expected) return sameFingerprint(expected, fingerprint) ? 'accept' : 'refuse';
+  return status === 'match' ? 'accept' : 'ask';
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@sharedenv/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "sharedenv CLI — pull and run with your zero-knowledge secrets, decrypted locally.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "secrets",
+    "env",
+    "dotenv",
+    "zero-knowledge",
+    "e2ee",
+    "cli"
+  ],
+  "homepage": "https://sharedenv.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SharedEnv/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SharedEnv/cli/issues"
+  },
+  "bin": {
+    "sharedenv": "bin/sharedenv.js"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.2.0"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}