agmsg-cloud 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/src/slot-advice.js

@@ -1,3 +1,4 @@
+import { setupCommand } from './recovery-key.js';
 import { shellArg } from './shell-arg.js';
 /**
  * Explain a slot that did not open, given the command that will now ask for the
@@ -65,6 +66,90 @@ export function adviseOnSlot(result, ctx) {
             };
     }
 }
+/**
+ * Explain a slot that did not open, given a command that will NOT ask for the
+ * recovery key — `connect`, which files the team's key into the vault silently
+ * or not at all.
+ *
+ * A second mapping rather than a second wording of the first: the sentences
+ * above all end in "the recovery key is typed and this run continues", and
+ * every one of them is false here. Nothing continues; the team is not in the
+ * vault, and what the person needs is the route that puts it there.
+ *
+ * The two live in one file, side by side, because they are one judgement read
+ * twice. `OpenResult['reason']` is a union and both switches are exhaustive, so
+ * a fifth reason cannot be answered in one of them and forgotten in the other —
+ * it fails to compile until both have looked at it.
+ *
+ * The `no-store` branch is why this exists at all. The prompting caller can say
+ * "the key is needed for each backup" and be done; here, the honest sentence is
+ * that this machine will never file silently, and a remedy that said "run
+ * `recovery setup` once and this stops happening" would be a route that does
+ * not exist on Windows or Linux.
+ */
+export function adviseOnSlotForSilentFiling(result, ctx) {
+    if (result.ok)
+        return { tone: 'silent', lines: [] };
+    // NAMED, and the argument is the point rather than a detail.
+    //
+    // `recovery setup` takes the team optionally now, and the no-argument form is
+    // the one its own documentation calls ordinary — which is why this printed it
+    // at first. But the broad form's success depends on every OTHER team the
+    // machine reports: one pass, no per-team isolation, so a `key.sh handoff`
+    // that fails for an unrelated team throws out of the loop and nothing is
+    // written. And if `remote.sh status --json` comes back short (agmsg#650) the
+    // target list can be empty, which refuses outright.
+    //
+    // Either way the person is sent to a command that can fail for a reason that
+    // has nothing to do with the team they just connected — and this is the one
+    // route they are given. Naming the team makes the remedy reach exactly the
+    // thing the sentence above it is about (raised in review).
+    const setup = `\`${setupCommand(ctx.team)}\``;
+    switch (result.reason) {
+        case 'no-slot':
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has no key slot for this vault, so the team was not backed up.',
+                    `Run ${setup} and type the recovery key once; after that this machine`,
+                    'files new teams itself.',
+                ],
+            };
+        case 'no-store':
+            // The one that must not promise a fix. There is no secure store to keep a
+            // slot in, so every future `connect` on this machine lands here too.
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has no secure store, so it cannot back up a team without the recovery',
+                    `key: the team was not backed up. Run ${setup} to back it up now.`,
+                    'This machine will need the key each time; a machine with a secure store will not.',
+                ],
+            };
+        case 'store-locked':
+            // Order matters here and only here: running setup against a locked store
+            // backs the team up but keeps no slot, so the next connect asks again.
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has a secure store but it refused: ' + result.detail,
+                    `The team was not backed up. Unlock the store, then run ${setup} —`,
+                    'in that order, so a key slot is kept and later teams are filed without asking.',
+                ],
+            };
+        case 'unusable':
+            return {
+                tone: 'warning',
+                lines: [
+                    'this machine has a key slot for this vault and its contents did not hold up: ' +
+                        result.detail,
+                    `The team was not backed up. Run ${setup}, which asks for the recovery`,
+                    'key and replaces the slot. Until then this team exists only on the machines',
+                    'holding it.',
+                ],
+            };
+    }
+}
 /** Render advice for a terminal. Empty string when there is nothing to say. */
 export function renderSlotAdvice(advice) {
     if (advice.lines.length === 0)

package/dist/src/vault-container.js

@@ -87,6 +87,45 @@ export function upsertTeam(container, entry) {
     const teams = [...others, entry].sort((a, b) => (identityOf(a) < identityOf(b) ? -1 : 1));
     return { format: CONTAINER_FORMAT, version: CONTAINER_VERSION, teams };
 }
+/**
+ * The same two key epochs, however they are ordered.
+ *
+ * A set comparison, not a sequence one: the epochs come out of a bundle the OSS
+ * side produced, and nothing promises the order is stable between two runs.
+ * Comparing them in order would report a change on a re-ordering and append a
+ * version identical to the one before it.
+ */
+export function sameEpochs(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const left = [...a].sort();
+    const right = [...b].sort();
+    return left.every((v, i) => v === right[i]);
+}
+/**
+ * Put one team into the container, unless its epochs are already the ones in
+ * there.
+ *
+ * The `written` half is the point. `recovery setup` documents itself as
+ * idempotent — "a run where no team's epochs have moved writes nothing and
+ * leaves the revision where it was" — and that promise belongs to the container,
+ * not to the command that happened to make it first. `connect` files a team the
+ * moment it is created and is re-runnable, so without this a second `connect`
+ * on a team already in the vault appends a version identical to the one before
+ * it, and the revision history stops meaning "something changed here".
+ *
+ * Kept beside `upsertTeam` rather than in either caller, because two copies of
+ * "has this actually moved" that drifted would disagree about whether a write
+ * was needed — and the one that said yes would silently win.
+ */
+export function upsertTeamIfMoved(container, entry) {
+    const key = identityOf(entry);
+    const already = container.teams.find((t) => identityOf(t) === key);
+    if (already && sameEpochs(already.key_ids, entry.key_ids)) {
+        return { container, written: false };
+    }
+    return { container: upsertTeam(container, entry), written: true };
+}
 export function serializeContainer(container) {
     return Buffer.from(JSON.stringify(container), 'utf8');
 }

package/dist/src/vault-filing.js

@@ -0,0 +1,62 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { openDeviceSlot } from './device-slot.js';
+import { keyHandoff, remoteBinding } from './oss.js';
+import { parseContainer, serializeContainer, upsertTeamIfMoved } from './vault-container.js';
+import { appendVaultVersionWithVdk, openVaultWithVdk, readAccountVault } from './vault-protocol.js';
+import { bundleKeyIds, slotAddress } from './commands/vault.js';
+/**
+ * File one team's handoff bundle into this account's vault, if that can be done
+ * silently.
+ *
+ * Fails closed in the sense that matters: it never invents a vault, never asks
+ * for a key, and never reports success for a write it did not make.
+ */
+export async function fileTeamInVaultSilently(config, client, team) {
+    const { identity, version } = await readAccountVault(client);
+    // No vault means there is no recovery key either — creating one here would
+    // mint a key and show it during a command nobody ran for that purpose.
+    if (!version)
+        return { filed: false, reason: 'no-vault' };
+    const opened = await openDeviceSlot(slotAddress(identity, version.vault_id, version.recovery_generation));
+    // Every way of not having a slot lands here, and none of them is an error:
+    // a machine that has never run `recovery setup`, a platform with no secure
+    // store, a locked keychain. The caller names the route instead.
+    if (!opened.ok)
+        return { filed: false, reason: 'no-slot', slot: opened };
+    const binding = await remoteBinding(config.scriptsDir, team);
+    const current = openVaultWithVdk(identity, version, opened.vdk);
+    const container = parseContainer(current.content);
+    const scratch = mkdtempSync(join(tmpdir(), 'agmsg-cloud-filing-'));
+    try {
+        const bundleFile = join(scratch, 'handoff.bundle');
+        await keyHandoff(config.scriptsDir, team, bundleFile);
+        const bundle = readFileSync(bundleFile);
+        // The same decision `recovery setup` makes, from the same function.
+        //
+        // `connect` is re-runnable — a second run on a team that is already
+        // connected continues to the registration rather than refusing — so
+        // without this it would append a version identical to the one before it
+        // every time. `recovery setup` documents itself as idempotent; a second
+        // writer that is not makes that sentence false about the account.
+        const { container: next, written } = upsertTeamIfMoved(container, {
+            server_instance_id: binding.serverInstanceId,
+            team_id: binding.teamId,
+            key_ids: bundleKeyIds(bundle),
+            bundle: bundle.toString('base64'),
+        });
+        if (!written) {
+            // Backed up, and this run is not what did it. Told apart from a write
+            // because the caller says "revision N" and there is no new N to say.
+            return { filed: true, wrote: false, revision: version.revision, teamCount: next.teams.length };
+        }
+        const result = await appendVaultVersionWithVdk(client, identity, version, opened.vdk, serializeContainer(next));
+        return { filed: true, wrote: true, revision: result.revision, teamCount: next.teams.length };
+    }
+    finally {
+        // The bundle is key material. Removed on every path this process controls,
+        // the same way the ceremony's snapshot is.
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",