aegis-desktop 1.0.10 → 1.0.13

package/vendor/record-vault.js

@@ -66,15 +66,39 @@
  * inspects what is *already* in the vault and names it, so the answer to "is a
  * key in there?" is a command rather than a memory.
  *
+ * ## Two backends: `aegiscloud` (default) and `rclone`
+ *
+ * The vault used to be rclone-or-nothing, and the default target
+ * (`gdrive:AEGIS-AGPL`) assumed a Drive remote the user had already
+ * configured by hand. On a fresh install that remote does not exist, so the
+ * first `fingerprint publish` failed with rclone's "didn't find section in
+ * config file" — the default was a folder the user could not have.
+ *
+ * So the *default* backend is now `aegiscloud`: the account this machine
+ * already registered for with `POST /api/v1/auth/register-device` (see
+ * client/auto-provision.js — the same device key every other cloud feature
+ * uses, so publishing needs no second sign-in). The bytes are stored per
+ * account, addressed by the same `<keyFingerprint>-<behaviour>.<stamp>` name,
+ * and read back through the same three-claim check (`present` / `unchanged` /
+ * `attested`) — a remote vault is only worth anything if the copy can be
+ * fetched and re-verified later.
+ *
+ * `rclone` remains a first-class backend for anyone who wants the record in
+ * *their own* Google Drive / S3 / whatever (`--backend rclone`, or simply
+ * `--remote gdrive`), because "where do my records live" is the user's
+ * decision and a vendor account is a default, not a requirement.
+ *
  * ## Testing
  *
- * Nothing here talks to a network directly: every remote operation is one
- * `rclone` invocation through `rcloneBinary()`, and the binary is overridable
- * (`AEGIS_VAULT_RCLONE`, `--rclone`). `test/fingerprint-vault.test.mjs` drives
- * the whole surface against a stub, so the suite is hermetic and never touches
- * the user's Drive. The remote/root are overridable the same way
- * (`AEGIS_VAULT_REMOTE`/`AEGIS_VAULT_ROOT`), which is also what keeps a
- * misconfigured vault from writing into some unrelated folder.
+ * Every remote operation goes through one dispatcher (`transportFor`), which is
+ * either the rclone adapter (`rcloneBinary()` overridable via
+ * `AEGIS_VAULT_RCLONE`) or the aegiscloud adapter (whose `fetch` is injectable
+ * through `o.fetch`). `test/cli-fingerprint-vault.test.mjs` drives the whole
+ * surface against a stub rclone, and `test/cli-fingerprint-cloud.test.mjs`
+ * against a stub HTTP vault, so the suite is hermetic and never touches the
+ * user's Drive or their account. The remote/root are overridable the same way
+ * (`AEGIS_VAULT_REMOTE`/`AEGIS_VAULT_ROOT`, `AEGIS_VAULT_BACKEND`), which is
+ * also what keeps a misconfigured vault from writing into an unrelated folder.
  */
 
 const crypto = require('node:crypto');
@@ -86,6 +110,18 @@ const { execFileSync } = require('node:child_process');
 const fp = require('./fingerprint.js');
 const authorship = require('./authorship-key.js');
 
+/**
+ * The backends a vault can live on.
+ *
+ * `aegiscloud` is the default because it is the only one that exists on a
+ * fresh install: it authenticates with the device key this machine already
+ * registered for, so publishing a record needs no second setup. `rclone` is
+ * kept for users who want the copy in a folder they own.
+ */
+const BACKEND_CLOUD = 'aegiscloud';
+const BACKEND_RCLONE = 'rclone';
+const DEFAULT_BACKEND = BACKEND_CLOUD;
+
 /** The folder the sealed records live in, and the folder that must not hold a key. */
 const DEFAULT_REMOTE = 'gdrive';
 const DEFAULT_ROOT = 'AEGIS-AGPL';
@@ -101,6 +137,11 @@ const INDEX_KIND = 'aegiscode.record.index';
 const RCLONE_ENV = 'AEGIS_VAULT_RCLONE';
 const REMOTE_ENV = 'AEGIS_VAULT_REMOTE';
 const ROOT_ENV = 'AEGIS_VAULT_ROOT';
+const BACKEND_ENV = 'AEGIS_VAULT_BACKEND';
+const API_BASE_ENV = 'AEGIS_API_BASE';
+
+/** Where the aegiscloud backend lives, and the routes it speaks. */
+const CLOUD_PREFIX = '/api/v1/vault';
 
 /** Every remote call is bounded: a hung rclone must not hang a mint or a GUI turn. */
 const RCLONE_TIMEOUT_MS = 60_000;
@@ -157,10 +198,18 @@ function rcloneBinary(env = process.env, argv = []) {
  * Where the vault is. Both halves are injectable because both are things a
  * caller can get wrong in a way that writes a record somewhere unintended.
  */
-function vaultTarget(env = process.env, argv = []) {
+function vaultTarget(env = process.env, argv = [], link = null) {
+  const remote = flag(argv, '--remote') || env[REMOTE_ENV] || (link && link.remote) || DEFAULT_REMOTE;
   return {
-    remote: flag(argv, '--remote') || env[REMOTE_ENV] || DEFAULT_REMOTE,
-    root: flag(argv, '--root') || env[ROOT_ENV] || DEFAULT_ROOT,
+    // `--backend` wins, then the env. A caller who names an rclone remote
+    // (`--remote gdrive`, `AEGIS_VAULT_REMOTE=r2`) is asking for THAT remote, so
+    // naming one switches the backend rather than being silently ignored by a
+    // cloud default — the old behaviour of reading `--remote` and then talking
+    // to aegiscloud would be the worst of both.
+    backend: backendFor(env, argv, remote, link),
+    remote,
+    root: flag(argv, '--root') || env[ROOT_ENV] || (link && link.root) || DEFAULT_ROOT,
+    apiBase: String(flag(argv, '--base') || env[API_BASE_ENV] || 'https://aegiscloud.org').replace(/\/+$/, ''),
     rclone: rcloneBinary(env, argv),
     // Carried so `rcloneRun` can hand the *injected* environment to the child.
     // Passing rclone the ambient process env instead made every AEGIS_VAULT_*
@@ -171,6 +220,35 @@ function vaultTarget(env = process.env, argv = []) {
   };
 }
 
+/**
+ * Which backend this target resolves to.
+ *
+ * Precedence, and each step is a user saying something specific:
+ *
+ *   1. `--backend` / `$AEGIS_VAULT_BACKEND` — explicit, and an unknown value is
+ *      an ERROR rather than a quiet fallback: "publish my records to aegiscloud"
+ *      silently becoming "…to your local Drive" (or the reverse) is a data
+ *      question, not a cosmetic one.
+ *   2. an explicit `--remote` / `$AEGIS_VAULT_REMOTE` — that is an rclone remote
+ *      name, so it selects rclone.
+ *   3. otherwise the default: `aegiscloud`.
+ */
+function backendFor(env, argv, remote, link = null) {
+  const explicit = String(flag(argv, '--backend') || env[BACKEND_ENV] || '').trim().toLowerCase();
+  if (explicit) {
+    if (explicit !== BACKEND_CLOUD && explicit !== BACKEND_RCLONE) {
+      throw new Error(`vault: unknown backend "${explicit}" — expected ${BACKEND_CLOUD} or ${BACKEND_RCLONE}`);
+    }
+    return explicit;
+  }
+  if (flag(argv, '--remote') || env[REMOTE_ENV]) return BACKEND_RCLONE;
+  // A link says where its own copy went; honouring it is what makes `anchor`
+  // work on a record published before the user changed their default.
+  if (link && (link.backend === BACKEND_CLOUD || link.backend === BACKEND_RCLONE)) return link.backend;
+  if (link && link.backend === undefined && link.remote && link.remote !== DEFAULT_REMOTE) return BACKEND_RCLONE;
+  return DEFAULT_BACKEND;
+}
+
 function remoteSpec(target, ...segments) {
   return `${target.remote}:${[target.root, ...segments].filter(Boolean).join('/')}`;
 }
@@ -229,6 +307,224 @@ function tempDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'aegis-vault-'));
 }
 
+// ---------------------------------------------------------------------------
+// the aegiscloud backend
+// ---------------------------------------------------------------------------
+
+/**
+ * The account key this machine already has, or null.
+ *
+ * Deliberately NOT a second sign-in: `client/credentials.js` is the one store
+ * the whole product resolves a key from, and a machine that has ever used any
+ * cloud feature has already registered a device (client/auto-provision.js) and
+ * saved that key there. Reading it means "publish to my vault" costs the user
+ * nothing beyond the account they already have; any other arrangement would be
+ * a second credential with its own expiry and its own way to be stale.
+ *
+ * `AEGIS_API_KEY` is honoured by credentials.js's own resolution order, so the
+ * env override works here for free.
+ */
+function cloudApiKey(o = {}) {
+  if (o.apiKey) return String(o.apiKey).trim();
+  const env = o.env || process.env;
+  try {
+    const credentials = require('./credentials.js');
+    // `dir` is passed explicitly and derived from the INJECTED env. Without it
+    // the store falls back to `os.homedir()`, so a host that scopes AEGIS_HOME
+    // (the desktop's data dir, every test) would publish to — or 401 against —
+    // whichever account the real user happens to be logged into.
+    return String(credentials.resolveApiKey({ env, dir: credentials.aegisHome(env) }).key || '').trim();
+  } catch {
+    // A host that cannot load the store is not a crash here: the caller gets
+    // "no account key" and the same instruction a first-time user gets.
+    return '';
+  }
+}
+
+/**
+ * One aegiscloud vault call.
+ *
+ * `fetch` is injectable (`o.fetch`) for the same reason `rcloneBinary` is: the
+ * suite must be hermetic, and a test that can only pass by reaching the real
+ * account is a test that gets skipped. Errors are wrapped with the server's own
+ * message, because "HTTP 401" is not a diagnosis — the account half of it is.
+ */
+async function cloudRun(target, method, route, { body = null, raw = false, timeout = RCLONE_TIMEOUT_MS, fetchImpl = null, apiKey = null } = {}) {
+  const key = apiKey || '';
+  if (!key) {
+    const err = new Error(
+      'vault: no AEGIS account key on this machine — the aegiscloud vault is the account ' +
+        'you already have. Run `aegiscode login`, or publish to a folder you own with ' +
+        '`--backend rclone --remote <name>`.',
+    );
+    err.code = 'ENOKEY';
+    throw err;
+  }
+  const doFetch = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  if (!doFetch) {
+    const err = new Error('vault: this Node has no global fetch — upgrade to Node 22+ to use the aegiscloud vault');
+    err.code = 'ENOFETCH';
+    throw err;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  let res;
+  try {
+    res = await doFetch(`${target.apiBase}${CLOUD_PREFIX}${route}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': key,
+        Authorization: `Bearer ${key}`,
+      },
+      body: body === null ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (e) {
+    const err = new Error(`vault: could not reach ${target.apiBase} — ${(e && e.message) || e}`);
+    err.code = 'ENETWORK';
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = null;
+  }
+  if (!res.ok) {
+    // A 404 on the collection route is not "the object is missing" — it is a
+    // server that predates `/api/v1/vault` (this client ships ahead of the
+    // account service it talks to). Saying "not found" there sends the user
+    // looking for a record that was never uploaded; name the real situation and
+    // the fallback that works today.
+    if (res.status === 404 && (route === '' || route.startsWith('?'))) {
+      const err = new Error(
+        `vault: ${target.apiBase} does not serve the account vault yet (${CLOUD_PREFIX} is ` +
+          'missing on this server). Publish to a folder you own instead: ' +
+          '`--backend rclone --remote <name> --root <folder>`.',
+      );
+      err.code = 'ENOVAULT';
+      err.status = 404;
+      throw err;
+    }
+    const msg = (data && (data.error || data.message)) || text.slice(0, 200) || `HTTP ${res.status}`;
+    const err = new Error(`vault: ${method} ${CLOUD_PREFIX}${route} failed — ${msg}`);
+    err.code = 'ECLOUD';
+    err.status = res.status;
+    throw err;
+  }
+  return raw ? text : data === null ? {} : data;
+}
+
+/**
+ * A route-safe id for one object.
+ *
+ * Encoded per SEGMENT, not with one `encodeURIComponent` over the whole name:
+ * the object lives under `records/`, so the slash is part of the route rather
+ * than part of a name. Encoding it as `%2F` works through Flask's `<path:>`
+ * converter, but it turns every message and every log line into
+ * `records%2F…`, and a proxy that rejects encoded slashes turns a publish into
+ * a mystery 404. The record names themselves are already filename-safe
+ * (client-side `baseName`), so this is belt-and-braces, not the guard.
+ */
+function cloudObject(target, name) {
+  return `/${String(name || '')
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => encodeURIComponent(segment))
+    .join('/')}`;
+}
+
+/**
+ * The transport the rest of this module talks to.
+ *
+ * Every remote operation is expressed once, here, in terms the module above
+ * understands — `put`, `cat`, `list`, `listRecursive` — so `publish`, `anchor`,
+ * `vault` and `--audit` do not each grow a second implementation per backend.
+ * The rclone half is the code that was already here, unchanged; the cloud half
+ * is the same four operations against `${apiBase}/api/v1/vault`.
+ */
+function transportFor(target, opts = {}) {
+  if (target.backend === BACKEND_CLOUD) {
+    const apiKey = cloudApiKey(opts);
+    const call = (method, route, extra) =>
+      cloudRun(target, method, route, { ...extra, fetchImpl: opts.fetch, apiKey });
+    return {
+      backend: BACKEND_CLOUD,
+      /** Upload one object. `rel` is root-relative (`records/x.json`). */
+      async put(rel, text) {
+        await call('PUT', cloudObject(target, remoteObjectName(rel)), { body: { content: text } });
+      },
+      /** Upload an existing local file, byte for byte — `publish` needs this. */
+      async putFile(rel, localPath) {
+        await this.put(rel, fs.readFileSync(localPath, 'utf8'));
+      },
+      /** Read one object, `null` when it is not there. */
+      async cat(rel) {
+        try {
+          const data = await call('GET', cloudObject(target, remoteObjectName(rel)));
+          return data && typeof data.content === 'string' ? data.content : null;
+        } catch (e) {
+          if (e.status === 404) return null;
+          throw e;
+        }
+      },
+      /** `{ Name, Size, ModTime, ID, Path }` for one directory (non-recursive). */
+      async list(rel) {
+        const data = await call('GET', `?dir=${encodeURIComponent(relativeToRoot(target, rel))}`);
+        return Array.isArray(data && data.files) ? data.files : [];
+      },
+      /** The same shape, for the whole vault (`vault --audit`). */
+      async listRecursive(prefix) {
+        const data = await call('GET', `?dir=${encodeURIComponent(relativeToRoot(target, prefix))}&recursive=1`);
+        return Array.isArray(data && data.files) ? data.files : [];
+      },
+      describe: `${target.apiBase} (account vault)`,
+    };
+  }
+
+  return {
+    backend: BACKEND_RCLONE,
+    async put(rel, text, { name = 'object' } = {}) {
+      const shelf = tempDir();
+      try {
+        const file = path.join(shelf, name);
+        fs.writeFileSync(file, text);
+        rcloneRun(target, ['copyto', file, remoteSpecOf(target, rel)]);
+      } finally {
+        fs.rmSync(shelf, { recursive: true, force: true });
+      }
+    },
+    /** Upload an existing local file, byte for byte — `publish` needs this. */
+    async putFile(rel, localPath) {
+      rcloneRun(target, ['copyto', localPath, remoteSpecOf(target, rel)]);
+    },
+    async cat(rel) {
+      try {
+        return rcloneRun(target, ['cat', remoteSpecOf(target, rel)]);
+      } catch (e) {
+        if (e.code === 'ERCLONE' && /not found|does not exist|error 404/i.test(e.stderr || e.message)) return null;
+        throw e;
+      }
+    },
+    async list(rel) {
+      return listRaw(target, rel);
+    },
+    async listRecursive(prefix) {
+      return rcloneLsjsonRecursive(target, prefix);
+    },
+    describe: `${target.remote}:${target.root}`,
+  };
+}
+
+/** `records/x.json` → `records/x.json`; strips the root/spec forms the readers accept. */
+function remoteObjectName(rel) {
+  return relativeToRoot({ remote: '', root: '' }, rel).replace(/^\/+/, '');
+}
+
 // ---------------------------------------------------------------------------
 // the guard: what may leave the machine
 // ---------------------------------------------------------------------------
@@ -426,7 +722,7 @@ function readRecord({ file = null, record = null, secret = null, env = process.e
  * @param {Date|string} [o.now]    publishedAt, injectable so a test can pin it
  * @returns {{ok: boolean, anchor: object, url: string|null, remotePath: string, dryRun: boolean}}
  */
-function publish(o = {}) {
+async function publish(o = {}) {
   const env = o.env || process.env;
   const argv = o.argv || [];
   const target = vaultTarget(env, argv);
@@ -460,10 +756,8 @@ function publish(o = {}) {
   // different names: `anchor` found one, `vault list` paired the other, and the
   // record's own link could not be fetched by the name it was stored under.
   const anchorName = `${recordName}${ANCHOR_SUFFIX}`;
-  const names = [
-    remoteSpec(target, RECORDS_DIR, recordName),
-    remoteSpec(target, RECORDS_DIR, anchorName),
-  ];
+  const recordRel = `${RECORDS_DIR}/${recordName}`;
+  const anchorRel = `${RECORDS_DIR}/${anchorName}`;
 
   const digest = sha256(text);
   const anchor = {
@@ -477,78 +771,83 @@ function publish(o = {}) {
     attestation: record.attestation,
     sha256: digest,
     bytes: Buffer.byteLength(text, 'utf8'),
+    // The backend is recorded because a link has to say WHERE the copy is for
+    // `anchor` to look in the right place: the same record can be published to
+    // the account vault and to a Drive folder, and the two are different links.
+    backend: target.backend,
     remote: target.remote,
     root: target.root,
     // `path` is for a human (and for pasting into rclone); `key` is the
     // root-relative form the reader uses. Both, because a single field that
     // means one thing to a person and another to rclone is how the root got
     // applied twice.
-    path: `${target.root}/${RECORDS_DIR}/${recordName}`,
-    key: `${RECORDS_DIR}/${recordName}`,
+    path: target.backend === BACKEND_CLOUD
+      ? `${CLOUD_PREFIX}/${recordRel}`
+      : `${target.root}/${recordRel}`,
+    key: recordRel,
     emittedAt: new Date(o.now || Date.now()).toISOString(),
     driveId: null,
     url: null,
     index: wantIndex ? `${target.root}/${RECORDS_DIR}/${INDEX_NAME}` : null,
   };
 
+  const transport = transportFor(target, o);
+
   if (dryRun) {
     return {
       ok: true,
       dryRun: true,
+      backend: target.backend,
       anchor,
       url: null,
       remotePath: anchor.path,
-      commands: [`rclone copyto ${file || '<record>'} ${names[0]}`, `rclone copyto <anchor> ${names[1]}`],
+      commands: target.backend === BACKEND_CLOUD
+        ? [`PUT ${target.apiBase}${CLOUD_PREFIX}/${recordRel}`, `PUT ${target.apiBase}${CLOUD_PREFIX}/${anchorRel}`]
+        : [`rclone copyto ${file || '<record>'} ${remoteSpec(target, recordRel)}`, `rclone copyto <anchor> ${remoteSpec(target, anchorRel)}`],
     };
   }
 
-  const shelf = tempDir();
-  try {
-    // Upload the *sealed bytes*. When publishing from a path, that is the file
-    // itself; otherwise it is written out first so a download can be diffed
-    // against the thing that was sealed.
-    const localRecord = file || path.join(shelf, recordName);
-    if (!file) fs.writeFileSync(localRecord, text);
-    rcloneRun(target, ['copyto', localRecord, names[0]]);
-
-    // The Drive id comes from a listing, not from a shareable-link call: a
-    // `link` would change the folder's sharing, and publishing a record must
-    // not touch who can read the vault.
-    const listed = listRaw(target, RECORDS_DIR);
-    const entry = listed.find((f) => f.Name === recordName) || null;
-    if (entry) {
-      anchor.driveId = entry.ID || null;
-      anchor.url = driveUrl(entry.ID);
-    }
+  // Upload the *sealed bytes*. When publishing from a path, that is the file
+  // itself; otherwise it is written out first so a download can be diffed
+  // against the thing that was sealed.
+  if (file) await transport.putFile(recordRel, file);
+  else await transport.put(recordRel, text, { name: recordName });
+
+  // The Drive id comes from a listing, not from a shareable-link call: a
+  // `link` would change the folder's sharing, and publishing a record must
+  // not touch who can read the vault. The cloud backend returns its own
+  // object id and url from the same kind of listing.
+  const listed = await transport.list(RECORDS_DIR);
+  const entry = listed.find((f) => String(f.Name) === recordName) || null;
+  if (entry) {
+    anchor.driveId = entry.ID || null;
+    anchor.url = entry.url || (target.backend === BACKEND_CLOUD ? null : driveUrl(entry.ID));
+  }
 
-    const localAnchor = file ? `${file}${ANCHOR_SUFFIX}` : null;
-    const anchorText = JSON.stringify(anchor, null, 2) + '\n';
-    const anchorFile = path.join(shelf, anchorName);
-    fs.writeFileSync(anchorFile, anchorText);
-    rcloneRun(target, ['copyto', anchorFile, names[1]]);
-    if (localAnchor) fs.writeFileSync(localAnchor, anchorText);
+  const localAnchor = file ? `${file}${ANCHOR_SUFFIX}` : null;
+  const anchorText = JSON.stringify(anchor, null, 2) + '\n';
+  await transport.put(anchorRel, anchorText, { name: anchorName });
+  if (localAnchor) fs.writeFileSync(localAnchor, anchorText);
 
-    let indexLines = null;
-    if (wantIndex) indexLines = appendIndex(target, anchor);
+  let indexLines = null;
+  if (wantIndex) indexLines = await appendIndex(target, anchor, transport);
 
-    return {
-      ok: true,
-      dryRun: false,
-      anchor,
-      url: anchor.url,
-      localAnchor,
-      remotePath: anchor.path,
-      bytes: anchor.bytes,
-      sha256: digest,
-      indexLines,
-    };
-  } finally {
-    fs.rmSync(shelf, { recursive: true, force: true });
-  }
+  return {
+    ok: true,
+    dryRun: false,
+    backend: target.backend,
+    anchor,
+    url: anchor.url,
+    localAnchor,
+    remotePath: anchor.path,
+    bytes: anchor.bytes,
+    sha256: digest,
+    indexLines,
+  };
 }
 
-/** Read one remote text file, `null` when it is not there. */
-function cat(target, remotePath) {
+/** Read one remote text file through rclone, `null` when it is not there. */
+function rcloneCat(target, remotePath) {
   try {
     return rcloneRun(target, ['cat', remoteSpecOf(target, remotePath)]);
   } catch (e) {
@@ -581,9 +880,12 @@ function listRaw(target, remotePath) {
  * ledger line loses nothing that cannot be rebuilt from the anchors beside each
  * record (`list` reads those, not this).
  */
-function appendIndex(target, anchor) {
-  const remotePath = `${RECORDS_DIR}/${INDEX_NAME}`;
-  const existing = cat(target, remotePath) || '';
+async function appendIndex(target, anchor, transport = transportFor(target)) {
+  const rel = `${RECORDS_DIR}/${INDEX_NAME}`;
+  // `cat` resolves null for a missing object on BOTH backends (the rclone
+  // adapter maps "not found", the cloud adapter maps a 404), so a first publish
+  // starts from an empty ledger rather than from an error.
+  const existing = (await transport.cat(rel)) || '';
   const line = JSON.stringify({
     kind: INDEX_KIND,
     id: anchor.id,
@@ -594,15 +896,8 @@ function appendIndex(target, anchor) {
     driveId: anchor.driveId,
     emittedAt: anchor.emittedAt,
   });
-  const shelf = tempDir();
-  try {
-    const file = path.join(shelf, INDEX_NAME);
-    fs.writeFileSync(file, existing + line + '\n');
-    rcloneRun(target, ['copyto', file, remoteSpecOf(target, remotePath)]);
-    return (existing.trim() ? existing.trim().split('\n').length : 0) + 1;
-  } finally {
-    fs.rmSync(shelf, { recursive: true, force: true });
-  }
+  await transport.put(rel, existing + line + '\n', { name: INDEX_NAME });
+  return (existing.trim() ? existing.trim().split('\n').length : 0) + 1;
 }
 
 // ---------------------------------------------------------------------------
@@ -634,17 +929,21 @@ function localAnchor(file) {
  * attestation no longer recomputes means the key moved on (or the record was
  * published by another key), and no digest of the file would ever show that.
  */
-function checkAnchor(o = {}) {
+async function checkAnchor(o = {}) {
   const env = o.env || process.env;
   const argv = o.argv || [];
-  const target = vaultTarget(env, argv);
-
   const anchor = o.anchor || (o.file ? localAnchor(o.file) : null);
   if (!anchor) {
     return { ok: false, reason: 'not linked — no anchor beside this record (publish it first)', present: false, unchanged: null, attested: null };
   }
-
-  const text = cat(target, anchor.key || anchor.path);
+  // The link says WHERE it was published, so the check reads the backend off the
+  // anchor rather than off this machine's current default: a record published to
+  // the account vault must still verify after the user switches their default to
+  // a Drive remote (and the other way round).
+  const target = vaultTarget(env, argv, anchor);
+  const transport = transportFor(target, o);
+
+  const text = await transport.cat(anchor.key || anchor.path);
   if (text === null) {
     // `present`, not `presence`: the field name is part of the answer, and a
     // consumer reading `.present` got `undefined` from this branch while the
@@ -688,49 +987,55 @@ function checkAnchor(o = {}) {
 }
 
 /** What is in the vault. Reads the anchors, which is why the ledger is optional. */
-function list(o = {}) {
+async function list(o = {}) {
   const env = o.env || process.env;
   const argv = o.argv || [];
   const target = vaultTarget(env, argv);
+  const transport = transportFor(target, o);
   const dir = RECORDS_DIR;
-  const files = listRaw(target, dir);
+  const files = await transport.list(dir);
   const anchors = files.filter((f) => String(f.Name).endsWith(ANCHOR_SUFFIX));
   const records = files.filter((f) => !String(f.Name).endsWith(ANCHOR_SUFFIX) && String(f.Name).endsWith('.json') && f.Name !== INDEX_NAME);
 
+  const rows = [];
+  for (const r of records) {
+    // Paired by the same rule that wrote it: the anchor is the record's name
+    // plus the suffix. Stripping `.json` off the record name first would look
+    // for `<stem>.anchor.json`, which is not the name anything was written
+    // under.
+    const anchorFile = anchors.find((a) => String(a.Name) === `${r.Name}${ANCHOR_SUFFIX}`);
+    let anchor = null;
+    if (anchorFile) {
+      // `cat` resolves the path against the root, so `records/<name>` here
+      // means `<remote>:<root>/records/<name>` — stated because getting this
+      // wrong is what put the ledger one directory too deep.
+      const text = await transport.cat(`${dir}/${anchorFile.Name}`);
+      try {
+        anchor = JSON.parse(text);
+      } catch {
+        anchor = { unreadable: true };
+      }
+    }
+    rows.push({
+      name: r.Name,
+      bytes: r.Size,
+      emittedAt: r.ModTime,
+      id: anchor ? anchor.id : null,
+      keyFingerprint: anchor ? anchor.keyFingerprint : null,
+      sha256: anchor ? anchor.sha256 : null,
+      driveId: (anchor && anchor.driveId) || r.ID || null,
+      url: (anchor && anchor.url) || r.url || driveUrl(r.ID),
+      linked: Boolean(anchor),
+    });
+  }
+
   return {
     ok: true,
+    backend: target.backend,
     remote: target.remote,
     root: target.root,
-    records: records.map((r) => {
-      // Paired by the same rule that wrote it: the anchor is the record's name
-      // plus the suffix. Stripping `.json` off the record name first would look
-      // for `<stem>.anchor.json`, which is not the name anything was written
-      // under.
-      const anchorFile = anchors.find((a) => String(a.Name) === `${r.Name}${ANCHOR_SUFFIX}`);
-      let anchor = null;
-      if (anchorFile) {
-        const text = cat(target, `${dir}/${anchorFile.Name}`);
-        // `cat` resolves the path against the root, so `records/<name>` here
-        // means `<remote>:<root>/records/<name>` — stated because getting this
-        // wrong is what put the ledger one directory too deep.
-        try {
-          anchor = JSON.parse(text);
-        } catch {
-          anchor = { unreadable: true };
-        }
-      }
-      return {
-        name: r.Name,
-        bytes: r.Size,
-        emittedAt: r.ModTime,
-        id: anchor ? anchor.id : null,
-        keyFingerprint: anchor ? anchor.keyFingerprint : null,
-        sha256: anchor ? anchor.sha256 : null,
-        driveId: (anchor && anchor.driveId) || r.ID || null,
-        url: (anchor && anchor.url) || driveUrl(r.ID),
-        linked: Boolean(anchor),
-      };
-    }),
+    where: transport.describe,
+    records: rows,
   };
 }
 
@@ -747,19 +1052,20 @@ function list(o = {}) {
  * capped: an audit that silently stops inspecting is worse than one that says
  * it did.
  */
-function audit(o = {}) {
+async function audit(o = {}) {
   const env = o.env || process.env;
   const argv = o.argv || [];
   const target = vaultTarget(env, argv);
+  const transport = transportFor(target, o);
   const max = Number(flag(argv, '--max')) || MAX_AUDIT_FILES;
 
   let files;
   try {
     // The whole root, recursively: the object this audit exists to find
     // (`keys/agent.key`) is deliberately outside `records/`.
-    files = rcloneLsjsonRecursive(target, '');
+    files = await transport.listRecursive('');
   } catch (e) {
-    return { ok: false, error: (e && e.message) || String(e), findings: [], checked: 0 };
+    return { ok: false, backend: target.backend, where: transport.describe, error: (e && e.message) || String(e), findings: [], checked: 0 };
   }
 
   const secret = o.secret || null;
@@ -780,7 +1086,7 @@ function audit(o = {}) {
     checked += 1;
     let text;
     try {
-      text = rcloneRun(target, ['cat', remoteSpecOf(target, rel)]);
+      text = await transport.cat(rel);
     } catch (e) {
       uninspected.push({ path: rel, reason: (e && e.message) || String(e) });
       continue;
@@ -791,8 +1097,10 @@ function audit(o = {}) {
 
   return {
     ok: findings.length === 0,
+    backend: target.backend,
     remote: target.remote,
     root: target.root,
+    where: transport.describe,
     checked,
     files: files.length,
     uninspected,
@@ -812,6 +1120,12 @@ function rcloneLsjsonRecursive(target, prefix) {
 module.exports = {
   DEFAULT_REMOTE,
   DEFAULT_ROOT,
+  DEFAULT_BACKEND,
+  BACKEND_CLOUD,
+  BACKEND_RCLONE,
+  CLOUD_PREFIX,
+  BACKEND_ENV,
+  API_BASE_ENV,
   RECORDS_DIR,
   INDEX_NAME,
   ANCHOR_SUFFIX,
@@ -833,6 +1147,10 @@ module.exports = {
   driveUrl,
   vaultTarget,
   rcloneBinary,
+  rcloneCat,
+  transportFor,
+  cloudApiKey,
+  backendFor,
   sha256,
   flag,
   has,