@sharedenv/cli 1.1.0 → 2.0.0

package/lib/api.js

@@ -101,6 +101,10 @@ export class ApiError extends Error {
 
 // Answers that say what to do next rather than what failed.
 const NEXT_STEP = {
+  1004:
+    'your email is not confirmed yet: open the link emailed to you when the account was ' +
+    'created, then run `sharedenv login` again (no email? sign in on the web app, it sends ' +
+    'a new link)',
   1013: 'this session has not answered the second factor — run `sharedenv login` again',
   1014: 'the second-factor confirmation is too old — run `sharedenv login` again',
 };
@@ -128,3 +132,19 @@ export async function listAll(client, path, what) {
     if (page >= (body?.pagination?.pages ?? 1)) return rows;
   }
 }
+
+// GET /org/list pages the organizations you OWN (`data`), and returns those you are in
+// without owning them whole (`member`, on every page): both, once each.
+export async function listOrgs(client) {
+  const orgs = new Map();
+  for (let page = 1; ; page += 1) {
+    const body = expectOk(
+      await client.call('GET', `/org/list?limit=${PAGE_SIZE}&page=${page}`),
+      'cannot list organizations'
+    );
+    for (const org of [...(body?.data || []), ...(body?.member || [])]) {
+      orgs.set(String(org._id), org);
+    }
+    if (page >= (body?.pagination?.pages ?? 1)) return [...orgs.values()];
+  }
+}

package/lib/auth.js

@@ -64,7 +64,12 @@ export async function unlockAccount(client, password) {
   try {
     privateKey = unwrapPrivateKey(keyring.encPrivateKey, password, keyring.kdf);
   } catch {
-    throw new Error('wrong password — could not unlock the vault');
+    const err = new Error(
+      'this password does not unlock the vault. If you reset it, the vault is still sealed ' +
+        'under the old one: sign in once on the web app and enter your recovery code there'
+    );
+    err.code = 'VAULT_SEALED';
+    throw err;
   }
   // 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".
@@ -73,3 +78,9 @@ export async function unlockAccount(client, password) {
   }
   return { privateKey, userId: keyring.userId };
 }
+
+// → your user id, or null (no keyring yet). Needs the session, not the password.
+export async function whoAmI(client) {
+  const res = await client.call('GET', '/keyring/me');
+  return res.status === 200 && res.body?.userId ? String(res.body.userId) : null;
+}

package/lib/crypto/kt.js

@@ -21,8 +21,9 @@
 // n". Whoever already knows a subject and a key (the person sealing to them) computes
 // the same hashes. Subjects: `user:<id>`, `team:<id>`.
 //
-// It only does arithmetic on hashes. Every client (browser, extension, command line)
-// computes the same hashes for the same entries.
+// It only does arithmetic on hashes, and the bookkeeping of what a client checked (the
+// record it keeps between two reads, below). No I/O: every client (browser, command
+// line) reads the log its own way and computes the same results from the same entries.
 
 import crypto from 'crypto';
 
@@ -98,3 +99,127 @@ export function replay(view, entries, { watch = {} } = {}) {
 // Is `publicKeyHex` the last key the log holds for `subject`?
 export const isLogged = (view, subject, publicKeyHex) =>
   view.latest[subjectHash(subject)] === keyHash(publicKeyHex);
+
+// ── What a client keeps between two reads ────────────────────────────────────────
+// One record per log: the view checked, how far each watched subject was checked (by
+// its hash), and the alerts its owner has not acknowledged yet:
+//   { seq, hash, latest, watched: { [subjectHash]: seq }, alerts: [{ kind, subject, seq }] }
+// kind 'foreign': entry `seq` logged a key that is not ours under `subject`.
+// kind 'unlogged': when the log stood at `seq`, our key was not the last one of `subject`.
+// An alert stays until acknowledged, whatever later reads find: a substitution that was
+// put back is still the trace of an attack, and a warning printed once (in a CI log, in
+// a closed tab) is easily missed.
+
+export const emptyRecord = () => ({ ...emptyView(), watched: {}, alerts: [] });
+
+const isAlert = (a) =>
+  a &&
+  (a.kind === 'foreign' || a.kind === 'unlogged') &&
+  typeof a.subject === 'string' &&
+  Number.isInteger(a.seq);
+
+// -> the record in what storage gave back; anything unusable starts over (the next read
+// replays the log from its first entry). A view kept by an earlier client, without
+// `watched`, is read again from the start once.
+export function toRecord(stored) {
+  const sane =
+    stored &&
+    Number.isInteger(stored.seq) &&
+    stored.seq >= 0 &&
+    typeof stored.hash === 'string' &&
+    stored.latest &&
+    typeof stored.latest === 'object';
+  if (!sane) return emptyRecord();
+  const watched = {};
+  if (stored.watched && typeof stored.watched === 'object' && !Array.isArray(stored.watched)) {
+    for (const [hashed, seq] of Object.entries(stored.watched)) {
+      if (Number.isInteger(seq) && seq >= 0 && seq <= stored.seq) watched[hashed] = seq;
+    }
+  }
+  return {
+    seq: stored.seq,
+    hash: stored.hash,
+    latest: stored.latest,
+    watched,
+    alerts: Array.isArray(stored.alerts) ? stored.alerts.filter(isAlert) : [],
+  };
+}
+
+const checkedUpTo = (record, subject) => record.watched[subjectHash(subject)] ?? 0;
+
+// Where the next read of the log starts: right after what was checked, unless `watch`
+// names a subject that was not checked that far (never watched, or left out of a read
+// since). Nobody read that part of the log on its behalf, so it is read again from the
+// first entry.
+export function readFrom(record, watch = {}) {
+  return Object.keys(watch).every((subject) => checkedUpTo(record, subject) === record.seq)
+    ? record.seq
+    : 0;
+}
+
+// Folds the entries read after `from` (readFrom) up to `head` into `record`.
+// -> { record, changed, view, foreign, unlogged, alerts }
+//   record    what to keep. A read that watched nothing gives back the record as it
+//             was: had it moved the position, the entries it went past would never be
+//             checked against anyone's name.
+//   changed   whether `record` is worth writing back
+//   view      the log as it now stands, kept or not (isLogged reads it)
+//   foreign, unlogged   what this read found
+//   alerts    every alert not acknowledged yet, those found by this read included
+// Throws KtError BROKEN: entries that do not chain or do not reach `head`, a log
+// shorter than what was checked, or a replay from the start that disagrees with it.
+export function absorb(record, from, entries, head, { watch = {} } = {}) {
+  if (head.seq < record.seq) {
+    throw new KtError('BROKEN', 'the log is shorter than what was already checked');
+  }
+  const start = from === 0 ? emptyView() : record;
+  const replayed = replay(start, entries, { watch });
+  const { view } = replayed;
+  if (view.seq !== head.seq || view.hash !== head.hash) {
+    throw new KtError('BROKEN', 'the log head does not match its entries');
+  }
+  // Read again from the start: the entry already checked must still be the same one.
+  if (from === 0 && record.seq > 0 && entries[record.seq - 1]?.hash !== record.hash) {
+    throw new KtError('BROKEN', 'the log no longer agrees with what was already checked');
+  }
+
+  const subjects = Object.keys(watch);
+  if (subjects.length === 0) {
+    return { record, changed: false, view, foreign: [], unlogged: [], alerts: record.alerts };
+  }
+
+  // Read again from the start, what a subject already had checked is not news (and its
+  // alerts may have been acknowledged since).
+  const foreign = replayed.foreign.filter((f) => f.seq > checkedUpTo(record, f.subject));
+  const { unlogged } = replayed;
+  const alerts = [...record.alerts];
+  const known = (a) =>
+    alerts.some(
+      (b) =>
+        b.kind === a.kind && b.subject === a.subject && (a.kind === 'unlogged' || b.seq === a.seq)
+    );
+  const found = [
+    ...foreign.map((f) => ({ kind: 'foreign', subject: f.subject, seq: f.seq })),
+    ...unlogged.map((subject) => ({ kind: 'unlogged', subject, seq: head.seq })),
+  ];
+  for (const a of found) if (!known(a)) alerts.push(a);
+
+  // The subjects watched now are checked up to the head; the others keep how far they
+  // were, and the next read that watches them again starts over.
+  const watched = { ...record.watched };
+  for (const subject of subjects) watched[subjectHash(subject)] = view.seq;
+  const next = { ...view, watched, alerts };
+  const sameWatched =
+    Object.keys(watched).length === Object.keys(record.watched).length &&
+    Object.entries(watched).every(([hashed, seq]) => record.watched[hashed] === seq);
+  const changed =
+    next.seq !== record.seq ||
+    next.hash !== record.hash ||
+    alerts.length !== record.alerts.length ||
+    !sameWatched;
+  return { record: next, changed, view, foreign, unlogged, alerts };
+}
+
+// The owner has read the alerts: the record without them. Whatever is still true is
+// found again by the next read.
+export const acknowledge = (record) => ({ ...record, alerts: [] });

package/lib/crypto/safeKey.js

@@ -0,0 +1,13 @@
+// Safe DEK helper. A "safe" is a container with one random 256-bit data
+// encryption key (DEK). Every secret value is AES-256-GCM encrypted under that
+// DEK, bound to its place (secretBlob.js); the DEK itself only ever travels sealed
+// (see Wallet.seal).
+//
+// Runs CLIENT-SIDE. A server only ever sees the resulting ciphertext blobs.
+
+import crypto from 'crypto';
+
+// → 32-byte DEK as a hex string.
+export function generateSafeKey() {
+  return crypto.randomBytes(32).toString('hex');
+}

package/lib/crypto.js

@@ -6,6 +6,7 @@ export {
   deriveAuthVerifier,
   unwrapPrivateKey,
 } from './crypto/kdf.js';
-export { openSecret } from './crypto/secretBlob.js';
+export { openSecret, sealSecret } from './crypto/secretBlob.js';
+export { generateSafeKey } from './crypto/safeKey.js';
 export { fingerprintOf } from './crypto/fingerprint.js';
-export { emptyView, replay, isLogged } from './crypto/kt.js';
+export { absorb, acknowledge, isLogged, readFrom, toRecord } from './crypto/kt.js';

package/lib/link.js

@@ -0,0 +1,46 @@
+// The vault a project uses: `.sharedenv.json`, written by `sharedenv link` in the
+// project's directory and found from there or any directory below it (like .nvmrc). It
+// holds the vault's id and nothing else - no secret - so it can be committed, and the
+// whole team works on the same vault. An id grants nothing: the server still decides
+// who opens the vault, and every command says which vault it used.
+
+import { readFileSync, writeFileSync } from 'fs';
+import path from 'path';
+
+export const LINK_FILE = '.sharedenv.json';
+const VAULT_ID = /^[a-f0-9]{24}$/i;
+
+// → { file, vault } — the nearest link from `dir` up, or null when there is none.
+export function findLink(dir = process.cwd()) {
+  for (let current = path.resolve(dir); ; current = path.dirname(current)) {
+    const file = path.join(current, LINK_FILE);
+    let text = null;
+    try {
+      text = readFileSync(file, 'utf8');
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw new Error(`cannot read ${file} (${err.code})`);
+    }
+    if (text !== null) return { file, vault: vaultOf(file, text) };
+    if (path.dirname(current) === current) return null;
+  }
+}
+
+function vaultOf(file, text) {
+  let vault;
+  try {
+    vault = JSON.parse(text)?.vault;
+  } catch {
+    vault = undefined;
+  }
+  if (typeof vault !== 'string' || !VAULT_ID.test(vault)) {
+    throw new Error(`${file} does not name a vault: run \`sharedenv link\` again`);
+  }
+  return vault.toLowerCase();
+}
+
+// → the file written.
+export function writeLink(dir, vault) {
+  const file = path.join(dir, LINK_FILE);
+  writeFileSync(file, `${JSON.stringify({ vault: String(vault) }, null, 2)}\n`);
+  return file;
+}

package/lib/safes.js

@@ -1,30 +1,88 @@
-// Reading a safe: find it, recover its key (DEK), decrypt every secret — locally. The
-// server only ever returns ciphertext.
+// Vaults: find one, open it (recover its key, the DEK, locally), read and write its
+// secrets, create one. The server only ever holds ciphertext.
 
-import { Wallet, openSecret } from './crypto.js';
+import { Buffer } from 'buffer';
+import { Wallet, generateSafeKey, openSecret, sealSecret } from './crypto.js';
 import { expectOk, listAll } from './api.js';
-import { PendingShareError, listPendingShares } from './shares.js';
+import { publicKeyOf } from './auth.js';
+import { PendingShareError, listPendingShares, personLabel } 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_-]+$/;
+export 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 const LEVELS = { read: 10, write: 50, admin: 90 };
+export const levelName = (level) =>
+  Object.keys(LEVELS).find((name) => LEVELS[name] === level) || String(level);
+
+export const listVaults = (client) => listAll(client, '/safes', 'vaults');
+
+// One line that tells a vault from another of the same name: its id, your access, whose
+// it is, and through which of your teams you reach it. `me`: your user id, when known.
+export function describeVault(row, me) {
+  const mine = me && String(row.ownerId) === String(me);
+  const owner = mine ? 'you' : row.owner ? personLabel(row.owner) : String(row.ownerId);
+  const teams = (row.teams || []).map((t) => (t.org?.name ? `${t.name} (${t.org.name})` : t.name));
+  return [
+    row.name,
+    String(row._id),
+    levelName(row.level),
+    `owner ${owner}`,
+    ...(teams.length ? [`team ${teams.join(', ')}`] : []),
+  ].join('  ');
+}
+
+// A vault by id, or by (case-insensitive) name among every vault you can open. A name
+// that several vaults answer to picks none of them: the candidates are listed. A share
+// still waiting for your answer is named as such rather than reported missing.
+// → the vault id.
 export async function resolveSafe(client, ref) {
-  if (SAFE_ID.test(ref)) return ref;
+  if (SAFE_ID.test(ref)) return ref.toLowerCase();
   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 matches = (await listVaults(client)).filter((s) => s.name?.toLowerCase() === name);
+  if (matches.length === 1) return String(matches[0]._id);
+  if (matches.length > 1) {
+    throw Object.assign(
+      new Error(
+        [
+          `"${ref}" names ${matches.length} vaults: give its id (-v <id>)`,
+          ...matches.map((row) => `  ${describeVault(row)}`),
+        ].join('\n')
+      ),
+      { exitCode: 2 }
+    );
+  }
   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}"`);
+  throw new Error(`no vault named "${ref}" (sharedenv vaults lists yours)`);
+}
+
+// GET /safes/:id — the vault, your paths to its key, its owner and your teams on it. A
+// share waiting for your answer opens nothing yet: said as such.
+export async function readVault(client, 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 vaults`'
+        );
+  }
+  return expectOk(res, 'cannot open the vault');
+}
+
+// Your access to a vault, from what GET /safes/:id says of your paths to it.
+export function accessOf(vault) {
+  const levels = [vault.membership?.level, ...(vault.teamAccess || []).map((t) => t.level)];
+  return Math.max(0, ...levels.filter((l) => typeof l === 'number'));
 }
 
 // Every DEK the caller's paths to a safe yield, CURRENT first: a direct envelope, or a
@@ -56,51 +114,139 @@ export function resolveDeks(privateKey, safe) {
   return deks;
 }
 
+// → the vault (readVault) and its `deks`, current first.
+export async function openVault(client, privateKey, safeId) {
+  const vault = await readVault(client, safeId);
+  const deks = resolveDeks(privateKey, vault);
+  if (deks.length === 0) {
+    throw new Error('no key to this vault on your account (not a member, or not provisioned yet)');
+  }
+  return { ...vault, deks };
+}
+
+// Every secret row of a vault: names in clear, values sealed. Names are checked: one
+// that is not a variable name, or twice the same, is refused.
+export async function listSecretRows(client, safeId) {
+  const seen = new Set();
+  const rows = await listAll(client, `/secrets/${safeId}`, 'secrets');
+  for (const row of rows) {
+    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 (seen.has(row.key)) throw new Error(`the server sent "${row.key}" twice for this vault`);
+    seen.add(row.key);
+  }
+  return rows;
+}
+
 // 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) {
+// under. The value must have been sealed where it was read (this vault, this name): a
+// blob moved there from another secret or another vault is refused.
+function decryptRow(deks, safeId, row) {
+  const place = { safeId, key: row.key };
   let misplaced = null;
   for (const dek of deks) {
     try {
-      return openSecret(dek, blob, place);
+      return openSecret(dek, row.ciphertextValue, 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`
-  );
+  if (misplaced) throw new Error(`refusing "${row.key}": ${misplaced.message}`);
+  throw new Error(`cannot decrypt "${row.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.
+// → { safe, secrets: { KEY: value } } — every secret of the vault, 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)
+  const vault = await openVault(client, privateKey, safeId);
+  const secrets = {};
+  for (const row of await listSecretRows(client, safeId)) {
+    secrets[row.key] = decryptRow(vault.deks, safeId, row);
+  }
+  return { safe: vault.safe, secrets };
+}
+
+// → { safe, value } — one secret, decrypted.
+export async function readSecret(client, privateKey, safeId, key) {
+  const vault = await openVault(client, privateKey, safeId);
+  const row = (await listSecretRows(client, safeId)).find((r) => r.key === key);
+  if (!row) throw new Error(`no key "${key}" in vault "${vault.safe.name}"`);
+  return { safe: vault.safe, value: decryptRow(vault.deks, safeId, row) };
+}
+
+// Adds or replaces secrets, sealed here under the vault's current key and bound to their
+// place. A vault someone lost access to still runs under the key they held: nothing new
+// is written under it until its key has changed — and that rotation re-encrypts every
+// secret, which the web app does.
+// `entries`: [[KEY, value]]. → { safe, added: [KEY], replaced: [KEY] }
+export async function setSecrets(client, privateKey, safeId, entries) {
+  const vault = await openVault(client, privateKey, safeId);
+  const { safe } = vault;
+  if (safe.pendingRotation) {
+    throw new Error(
+      `"${safe.name}" must change its key first (someone lost access to it): an admin of ` +
+        'the vault opens it in the web app, which does it - then retry'
     );
-    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 [dek] = vault.deks;
+  const keyVersion = safe.keyVersion || 1;
+  const existing = new Map((await listSecretRows(client, safeId)).map((r) => [r.key, r]));
+  const added = [];
+  const replaced = [];
+  for (const [key, value] of entries) {
+    const ciphertextValue = JSON.stringify(sealSecret(dek, value, { safeId, key }));
+    const row = existing.get(key);
+    if (row) {
+      expectOk(
+        await client.call('PUT', `/secrets/${safeId}/${row._id}`, { ciphertextValue, keyVersion }),
+        `cannot replace "${key}"`
+      );
+      replaced.push(key);
+    } else {
+      expectOk(
+        await client.call('POST', `/secrets/${safeId}`, { key, ciphertextValue, keyVersion }),
+        `cannot add "${key}"`
+      );
+      added.push(key);
+    }
+  }
+  return { safe, added, replaced };
+}
 
-  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)');
+// Removes secrets by name; every name must exist, or nothing is removed. No key needed:
+// the server only drops ciphertext.
+export async function unsetSecrets(client, safeId, keys) {
+  const rows = new Map((await listSecretRows(client, safeId)).map((r) => [r.key, r]));
+  const missing = keys.filter((key) => !rows.has(key));
+  if (missing.length) {
+    throw new Error(`no key ${missing.map((k) => `"${k}"`).join(', ')} in this vault`);
   }
+  for (const key of keys) {
+    expectOk(
+      await client.call('DELETE', `/secrets/${safeId}/${rows.get(key)._id}`),
+      `cannot remove "${key}"`
+    );
+  }
+}
 
-  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 });
+// A new vault, yours: a fresh DEK, sealed to your own key here. A name you already see
+// is refused — it would stop telling the two vaults apart. → the vault ({ _id, name }).
+export async function createVault(client, privateKey, name) {
+  const taken = (await listVaults(client)).find(
+    (s) => s.name?.toLowerCase() === String(name).toLowerCase()
+  );
+  if (taken) {
+    throw new Error(
+      `you already have a vault named "${taken.name}" (${taken._id}): pick another name`
+    );
   }
-  return secrets;
+  const dek = generateSafeKey();
+  const sealedSafeKey = wallet.seal(privateKey, publicKeyOf(privateKey), Buffer.from(dek, 'hex'));
+  const body = expectOk(
+    await client.call('POST', '/safes', { name, sealedSafeKey: JSON.stringify(sealedSafeKey) }),
+    'cannot create the vault'
+  );
+  return body.safe;
 }

package/lib/shares.js

@@ -13,7 +13,7 @@ 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 ` +
+        `your answer: run \`sharedenv vaults\` to review it, then \`sharedenv accept ` +
         `${share.safeId}\` (or \`decline\`)`
     );
     this.code = 'SHARE_PENDING';
@@ -21,13 +21,16 @@ export class PendingShareError extends Error {
   }
 }
 
-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;
+// "First Last (username)", as the API resolves a person (`{ _id, username, ... }`).
+export function personLabel(person) {
+  const p = person || {};
+  const name = [p.firstName, p.lastName].filter(Boolean).join(' ').trim();
+  if (!p.username) return String(p._id || 'unknown');
+  return name ? `${name} (${p.username})` : p.username;
 }
 
+export const senderLabel = (share) => personLabel(share?.from);
+
 // → { 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) {
@@ -41,15 +44,37 @@ export async function listPendingShares(client) {
   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;
+// A pending share by its vault's id or name; `teamRef` (a team's id or name): among the
+// shares to that team. Two that answer to the same names are listed, never one picked.
+// → { safeId, teamId } (teamId null for a share to you).
+export async function resolvePendingShare(client, ref, teamRef) {
   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);
+  const same = (a, b) => String(a ?? '').toLowerCase() === String(b).toLowerCase();
+  const rows = teamRef
+    ? team.filter((p) => same(p.teamId, teamRef) || same(p.team?.name, teamRef))
+    : direct;
+  const matches = rows.filter((p) => same(p.safeId, ref) || same(p.safe?.name, ref));
+  if (matches.length === 0) {
+    throw new Error(`no pending share named "${ref}"${teamRef ? ` for team "${teamRef}"` : ''}`);
+  }
+  if (matches.length > 1) {
+    throw Object.assign(
+      new Error(
+        [
+          `"${ref}" names ${matches.length} pending shares: give the vault id` +
+            (teamRef ? ' and the team id' : ''),
+          ...matches.map(
+            (p) =>
+              `  ${p.safe?.name}  ${p.safeId}  from ${senderLabel(p)}` +
+              (p.teamId ? `  for team ${p.team?.name} (${p.teamId})` : '')
+          ),
+        ].join('\n')
+      ),
+      { exitCode: 2 }
+    );
+  }
+  const [match] = matches;
+  return { safeId: String(match.safeId), teamId: teamRef ? String(match.teamId) : null };
 }
 
 function senderKeyOf(share) {
@@ -75,7 +100,9 @@ export async function openPendingShare(client, privateKey, safeId) {
 }
 
 // The sender's key (and the team key a team share moves to) is the directory's word:
-// it must be the last key the public key log holds for them. `log`: { store }.
+// it must be the last key the public key log holds for them. `log`: { store, watch },
+// the watch of the unlock (bin/sharedenv.js): this read checks the entries it goes past
+// against every key we hold, like any other (lib/transparency.js `syncLog`).
 async function assertSenderLogged(client, log, opened, team) {
   const { view } = await syncLog(client, log);
   assertLogged(view, [