agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/commands/vault.js

@@ -0,0 +1,478 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CourierClient } from '../api.js';
+import { connectedTeams, keyHandoff, remoteBinding, unlockAuthenticatedBundle } from '../oss.js';
+import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
+import { generateRecoveryKey, normalizeRecoveryKey, promptRecoveryKey, showRecoveryKey, } from '../recovery-key.js';
+import { appendVaultVersionWithVdk, createVault, openVaultWithVdk, readAccountVault, vdkFromRecoveryKey, } from '../vault-protocol.js';
+import { openDeviceSlot, saveDeviceSlot } from '../device-slot.js';
+import { adviseOnSlot, renderSlotAdvice } from '../slot-advice.js';
+import { emptyContainer, parseContainer, selectTeam, serializeContainer, upsertTeam, } from '../vault-container.js';
+// The two recovery commands: resolve the team, obtain the bundle from the OSS
+// side, get the recovery key from the terminal, and hand off to
+// vault-protocol.ts for everything that talks to the server.
+//
+// The file, the functions and the storage are still named "vault" — that is
+// what the thing IS, and the spec calls it that. Only the two commands were
+// renamed, because `vault put` read as filing a copy away rather than as
+// preparing to recover. Every heading below names the CURRENT command.
+// Where this machine's key slot lives for a vault: the deployment, the account,
+// the vault, and the generation. All four, because a slot must not be carried to
+// another deployment, another account, another vault, or forward across a
+// re-issuance.
+//
+// The generation is read from the version the server just returned, with no
+// default anywhere on this side. A local fallback of 1 would let a server that
+// omits the field name generation 1 by omission, and — worse — a slot saved
+// under a made-up 1 would be indistinguishable from a legitimate generation-1
+// slot once a re-issuance produced one.
+function slotAddress(identity, vaultId, generation) {
+    return {
+        vaultServiceId: identity.vaultServiceId,
+        accountId: identity.accountId,
+        vaultId,
+        recoveryGeneration: generation,
+    };
+}
+/**
+ * Get the vault's data key without asking for the recovery key if this machine
+ * can avoid it.
+ *
+ * This is the whole point of the device slot, and the owner's requirement: the
+ * master key should not come out unless a machine is lost. A machine that has
+ * backed up before opens its own slot and never prompts. Every other machine —
+ * and every machine on a platform with no secure store — falls back to the key,
+ * which is what every machine did before this existed.
+ *
+ * Nothing here is a dead end. Each way of failing to open a slot continues to
+ * the same place; what differs is what the person is told, and that judgement
+ * lives in slot-advice.ts rather than here.
+ */
+async function vdkForVault(identity, version, team) {
+    const address = slotAddress(identity, version.vault_id, version.recovery_generation);
+    const opened = await openDeviceSlot(address);
+    if (opened.ok) {
+        // Proving the slot's key is THIS vault's key is not done here — the callers
+        // both open or append with it, and both of those fail closed on a key that
+        // does not fit. A check here would be a third place that has to agree.
+        return { vdk: opened.vdk, usedRecoveryKey: false };
+    }
+    const advice = renderSlotAdvice(adviseOnSlot(opened, { team }));
+    if (advice)
+        process.stdout.write(advice);
+    const recoveryKey = normalizeRecoveryKey(await promptRecoveryKey('Recovery key: '));
+    return { vdk: await vdkFromRecoveryKey(version, recoveryKey), usedRecoveryKey: true };
+}
+/**
+ * Keep this machine's slot, so the next run does not ask for the key.
+ *
+ * Called AFTER the vault write, not before. The design's crash order puts the
+ * device-wrap durable write first (recovery-vault-v1.md:533), and that order
+ * exists for the end state where the recovery key is shown LAST and can be
+ * re-derived from this slot. Today the key is shown before anything is stored,
+ * so no vault can exist that nobody can open, and writing the slot first would
+ * instead leave a slot addressed to a vault that was never created — one per
+ * failed attempt, since the address carries the vault id. WHEN THE KEY MOVES TO
+ * BEING SHOWN LAST, THIS ORDER MUST FLIP.
+ *
+ * A failure here never fails the command. The backup landed; the slot is what
+ * makes the next one keyless, and saying "the backup failed" because a keychain
+ * refused would be false.
+ */
+async function keepSlot(address, vdk) {
+    const saved = await saveDeviceSlot(address, vdk);
+    if (saved.ok) {
+        process.stdout.write('this machine now holds a key slot for this vault; later backups will not ask ' +
+            'for the recovery key\n');
+        return;
+    }
+    // Named, not swallowed. Someone who was told the key would stop being needed,
+    // and is then asked for it next time, is owed the reason — and there is no
+    // plaintext fallback here that would make it "work" instead.
+    process.stdout.write(`note: this machine could not keep a key slot (${saved.reason}), so the recovery ` +
+        'key will be needed again next time.\n');
+}
+// Whether a team's material is the same material, judged on the key epochs the
+// bundle declares rather than on its bytes.
+//
+// The ciphertext differs every run (nonce), and whether the bundle itself is
+// byte-stable is not something this side has established — so neither can carry
+// the comparison. `key_ids` are the epochs, they are already stored per entry,
+// and they are exactly what "the key situation has not changed" means. Compared
+// as a set: the order the exporter lists them in is not part of the fact.
+/**
+ * The key that decides whether two records name the same team.
+ *
+ * One function, so both sides of every comparison are built the same way — a
+ * separator chosen twice is a separator that eventually differs. Framed rather
+ * than joined: `('a|b','c')` and `('a','b|c')` are different pairs and must not
+ * produce one key, which is the collision the request digest had to be fixed
+ * for. These two values are uuids today, so no pair can collide — the framing
+ * is here so that stays true if either ever stops being one.
+ *
+ * Written after the first version put a literal separator inside a template and
+ * a NUL character ended up in the source, which made the whole file binary to
+ * `grep`. Both sides still agreed, so nothing failed; the file simply stopped
+ * answering searches.
+ */
+function vaultTeamKey(serverInstanceId, teamId) {
+    return JSON.stringify([serverInstanceId, teamId]);
+}
+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]);
+}
+/**
+ * `recovery setup` — put the keys of every team THIS MACHINE reports into the
+ * account's vault.
+ *
+ * NO ARGUMENT IS THE ORDINARY FORM. The vault holds one recovery key for the
+ * whole account, so "set up recovery" is an account-level act; naming a team
+ * made it something to repeat every time a team was added, which is the folding
+ * this design exists to do. A team may still be named, for adding one on its
+ * own.
+ *
+ * NOT "every team on the account", and the difference is load-bearing until
+ * fujibee/agmsg#650 lands. The set comes from `remote.sh status --json`, which
+ * drops a team it could not read and exits 0 — so an active team that has never
+ * been backed up can be missed with nothing said. Every sentence describing this
+ * command, here and in `--help` and in the README, stops at what the machine
+ * reported for exactly that reason. Widening them is the change that closes
+ * #182, and it comes after #650, not before.
+ *
+ * IDEMPOTENT. A run where no team's epochs have moved writes nothing and leaves
+ * the revision where it was. `setup` that appended an identical version every
+ * time was a name promising one thing and a behaviour doing another — and the
+ * cost is not storage, it is that a version history exists to show when
+ * something changed, and identical versions make it unreadable.
+ */
+export async function cmdVaultPut(config, args) {
+    // Same check connect gets. Without it a machine with no agmsg install runs
+    // straight into `bash exited 127: …/remote.sh: No such file or directory` —
+    // the same absence connect reports as a named checklist.
+    ensurePreflight(preflight(config.scriptsDir, NEEDS.vaultPut));
+    const client = new CourierClient(config);
+    // Two questions, and they are not the same one.
+    //
+    //   observed   every team whose status this machine could READ, whatever it
+    //              said. This is what makes "the vault holds a team that did not
+    //              appear" mean something: without it, a team disconnected here
+    //              is indistinguishable from one whose status could not be read.
+    //   targets    those with an ACTIVE binding. Only these may be filed — a
+    //              disconnected team's ids are a leftover, and a vault entry
+    //              under one records a backup against a remote this machine is no
+    //              longer bound to.
+    const observed = args.team === undefined ? await connectedTeams(config.scriptsDir) : [];
+    const targets = args.team === undefined
+        ? observed.filter((t) => t.state === 'active')
+        : [{ team: args.team, ...(await remoteBinding(config.scriptsDir, args.team)) }];
+    if (targets.length === 0) {
+        throw new Error('no team on this machine is connected to the hosted service, so there are no keys to back up.\n' +
+            'Run `agmsg-cloud connect <team>` first, or name a team if one is connected under a different name.');
+    }
+    // The account's vault, not this team's: one vault, one recovery key. A second
+    // team finds the vault that already exists and is added to it.
+    const { identity, version } = await readAccountVault(client);
+    let recoveryKey = null;
+    let vdk = null;
+    // Whether this run had to reach the key. It decides whether a slot is worth
+    // keeping afterwards: a run the slot already answered has one, and saving
+    // again would mint a fresh KEK and replace a working slot for nothing.
+    let askedForTheKey = true;
+    let container;
+    // Whether a key was put on this person's screen during this run. It decides
+    // what a later failure has to tell them: a key they wrote down that never
+    // came into use is worse than no key, because they will keep it.
+    if (version) {
+        // This machine's slot first. The recovery key is only asked for when the
+        // slot cannot answer — which is what makes "shown once, then filed away" a
+        // livable instruction rather than a thing nobody follows.
+        //
+        // The prompt, when it happens, is for the ACCOUNT's key. Asking "for team
+        // X" was true when a team had its own vault; saying it now would teach
+        // someone to expect a different key per team, which is the belief the
+        // account vault exists to remove.
+        const obtained = await vdkForVault(identity, version, args.team ?? targets[0].team);
+        vdk = obtained.vdk;
+        askedForTheKey = obtained.usedRecoveryKey;
+        // Open before writing. The container has to be read to add a team to it,
+        // and opening it is also what proves this key is the vault's key — a
+        // mistyped key derives a valid but different VDK, and a version stored
+        // under it is unopenable at exactly the moment there is no way back.
+        const opened = openVaultWithVdk(identity, version, vdk);
+        container = parseContainer(opened.content);
+    }
+    else {
+        // The one moment the recovery key exists in the clear.
+        //
+        // Generated ONCE per execution and never regenerated inside it. The
+        // previous version showed the key, asked for it back, and minted a fresh
+        // one if the retype missed — so the sentence "write this down, it is shown
+        // once" was followed, in the same run, by making what they wrote down
+        // useless. Anything that fails after this point fails with THIS key, and
+        // the failure says so.
+        const minted = generateRecoveryKey();
+        recoveryKey = normalizeRecoveryKey(minted);
+        // Shown BEFORE anything is stored, and this order is load-bearing.
+        //
+        // Showing it after the upload reads better — the vault exists, so the key
+        // opens something — but it adds a failure this one does not have: a crash
+        // between the upload and the screen leaves a vault encrypted under a key
+        // nobody has ever seen, and no recovery key can be produced for it again.
+        // A key on paper for a vault that was never created is recoverable by
+        // throwing the paper away; that is not.
+        //
+        // The device slot does NOT change this, which is worth stating because it
+        // sounds like it should. The slot is what makes later runs keyless, and it
+        // is written after the vault exists — so at THIS point in a first run there
+        // is nothing on this machine the key could be re-derived from. Showing last
+        // becomes safe only when the slot is durable before the vault is created,
+        // and that ordering is a separate change with its own failure to think
+        // through (a slot addressed to a vault that was never made).
+        await showRecoveryKey(minted, args.team);
+        container = emptyContainer();
+    }
+    // THE ENUMERATION IS NOT FAIL-CLOSED, AND THIS DOES NOT PRETEND TO FIX THAT.
+    //
+    // `remote.sh status --json` with no team DROPS a team it could not read and
+    // still exits 0, and the single-team form cannot tell "never connected" from
+    // "could not be read" either — same message, same exit code. Measured, and
+    // filed as fujibee/agmsg#650.
+    //
+    // The first version of this REFUSED when the vault held a team the run did
+    // not see. That was wrong, and the reason is worth keeping: a team
+    // deliberately disconnected here disappears from the enumeration too, and the
+    // vault keeps its entry forever by design — so the refusal fired every run,
+    // for the one reason that is not a problem, with no way out. Refusing on a
+    // distinction the system cannot draw treats "unknown" as "wrong".
+    //
+    // So it reports instead. What was not seen is put on the screen by name and
+    // the judgement goes back to the operator, who is the only party that knows
+    // whether they disconnected it. That leaves a real gap — nobody who does not
+    // read the output is protected — and the gap is smaller than a command that
+    // cannot be run.
+    //
+    // When #650 lands this can become a refusal again, because by then a team
+    // that could not be read will say so.
+    const seenThisRun = new Set(observed.map((t) => vaultTeamKey(t.serverInstanceId, t.teamId)));
+    const unseen = args.team === undefined
+        ? container.teams.filter((e) => !seenThisRun.has(vaultTeamKey(e.server_instance_id, e.team_id)))
+        : [];
+    // Seen, and deliberately not filed. Kept apart from `unseen` because they are
+    // different facts: this machine HEARD about these, and the ones above it did
+    // not hear about at all.
+    const disconnected = observed.filter((t) => t.state === 'disconnected');
+    // WHAT THIS RUN COVERED, BY NAME. Written once, so both exits below say the
+    // same thing — a sentence written twice is one that eventually disagrees with
+    // itself, and these two paths differ in everything else.
+    //
+    // NO COUNT WITHOUT ITS MEMBERS. What the operator saw on the production
+    // walkthrough was `stored revision 3 — team 'rc3walk' backed up; 2 teams`,
+    // and the "2 teams" never said which two. A count reads as "the account is
+    // backed up", which is wider than what was checked: the set came from what
+    // the local store reported, and that store can come back short without
+    // saying so (agmsg#650).
+    //
+    // The first version of this got it wrong in its own way — it printed the
+    // heading "Covered" and then listed only the DISCONNECTED teams, because the
+    // backed-up ones are not known until the loop below has run. Hence the
+    // parameters: the groups are passed in rather than closed over, so the
+    // heading cannot outrun what is under it.
+    const coverage = (written, unchanged) => {
+        const group = (title, members) => members.length === 0 ? [] : [`\n  ${title}\n`, ...members.map((m) => `    ${m}\n`)];
+        // The first two hold for either form — a run that names one team still has
+        // to say what it did with it. The rest are about the ENUMERATION, so they
+        // only mean anything when the enumeration is what chose the set.
+        const enumerated = args.team === undefined;
+        const lines = [
+            ...group('Backed up in this revision:', written),
+            ...group('Already current, nothing to write:', unchanged),
+            ...(!enumerated
+                ? []
+                : group('Disconnected on this machine, left as they are:', disconnected.map((t) => t.team))),
+            // Ids, because a team that never reported has no local name here to
+            // print — the same absence that put it on this list. Said plainly rather
+            // than dressed up as an instruction: this machine does not know whether
+            // these were disconnected on purpose, and the operator does.
+            ...(!enumerated
+                ? []
+                : group('In the vault, but not reported by this machine on this run:', unseen.map((e) => `${e.team_id}  (server ${e.server_instance_id})`))),
+        ];
+        if (unseen.length > 0) {
+            lines.push('\n  Those entries are untouched. If you disconnected them here, nothing is\n', '  wrong. If you did not, this machine could not read their state and they\n', '  were not re-checked — that is agmsg#650, and it cannot be told apart\n', '  from here.\n');
+        }
+        // Said only by the form that DERIVED its set. A run given a team covered
+        // what it was told to; claiming it covered what the store reported would
+        // be a statement about an enumeration that never ran.
+        if (enumerated) {
+            lines.push("\n  That is every team this machine's store reported. A team connected only\n", '  on another machine is backed up by running this there.\n');
+        }
+        return lines.join('');
+    };
+    const scratch = mkdtempSync(join(tmpdir(), 'agmsg-cloud-'));
+    try {
+        // One pass over every target. A team whose declared epochs already match
+        // what the vault holds is left exactly as it is — not re-sealed under a
+        // fresh nonce, which would be a new version saying nothing new.
+        let next = container;
+        const written = [];
+        const unchanged = [];
+        for (const [i, target] of targets.entries()) {
+            const bundleFile = join(scratch, `handoff-${i}.bundle`);
+            await keyHandoff(config.scriptsDir, target.team, bundleFile);
+            const bundle = readFileSync(bundleFile);
+            const keyIds = bundleKeyIds(bundle);
+            const already = next.teams.find((e) => e.server_instance_id === target.serverInstanceId && e.team_id === target.teamId);
+            if (already && sameEpochs(already.key_ids, keyIds)) {
+                unchanged.push(target.team);
+                continue;
+            }
+            next = upsertTeam(next, {
+                server_instance_id: target.serverInstanceId,
+                team_id: target.teamId,
+                key_ids: keyIds,
+                bundle: bundle.toString('base64'),
+            });
+            written.push(target.team);
+        }
+        // Nothing moved, and the vault already exists: there is no version to
+        // write. Saying "stored revision N+1" here would be true of the server and
+        // false about the account — the point of a revision is that something is
+        // different in it.
+        if (written.length === 0 && version && vdk) {
+            // The headline carries no bare count: what "up to date" covers is the
+            // list below it, and a number on its own is the thing this was reported
+            // for.
+            process.stdout.write(`already up to date — nothing has new keys. Revision stays at ${version.revision}.\n`);
+            process.stdout.write(coverage(written, unchanged));
+            // A run that had to type the key still earns a slot: the key is in hand,
+            // and the next run should not ask again just because this one had nothing
+            // to store.
+            if (askedForTheKey) {
+                await keepSlot(slotAddress(identity, version.vault_id, version.recovery_generation), vdk);
+            }
+            return;
+        }
+        const content = serializeContainer(next);
+        // The address this machine's slot is kept at, decided by which write
+        // happened: an append addresses the vault that already exists, a create
+        // addresses the one it just made — and takes the generation from the create
+        // rather than restating that a new vault is generation 1.
+        let address;
+        let revision;
+        if (version && vdk) {
+            const result = await appendVaultVersionWithVdk(client, identity, version, vdk, content);
+            revision = result.revision;
+            address = slotAddress(identity, version.vault_id, version.recovery_generation);
+        }
+        else {
+            if (recoveryKey === null)
+                throw new Error('unreachable: a create without a recovery key');
+            const created = await createVault(client, identity, recoveryKey, content);
+            revision = created.revision;
+            vdk = created.vdk;
+            address = slotAddress(identity, created.vaultId, created.recoveryGeneration);
+        }
+        // `; 2 teams in this account's vault` used to end this line. It is the
+        // count the walkthrough operator read and could not act on — it never said
+        // WHICH two, and a bare number here reads as a statement about the account
+        // rather than about what this run saw. The groups below say both.
+        process.stdout.write(`stored revision ${revision}${version ? '' : ' (vault created)'}\n`);
+        // WHAT WAS COVERED IS WHAT THIS MACHINE REPORTED, and that is what the line
+        // says. It used to end at the count above, which reads as "the account is
+        // backed up" — a claim wider than the thing that was checked, since the
+        // enumeration this ran on can come back short without saying so
+        // (agmsg#650). Teams already in the vault are covered by the refusal
+        // higher up; a team that has never been in it cannot be seen from here at
+        // all, so the sentence stops at the machine rather than the account.
+        process.stdout.write(coverage(written, unchanged));
+        // After the write, and only when this run had to reach the key. A run the
+        // slot already answered has a working slot at this address; saving again
+        // would mint a fresh KEK, replace it, and touch the keychain on every
+        // routine backup — for a machine that is already in the state the slot
+        // exists to produce. The same condition governs the restore path below,
+        // and it has to be the same condition in both or one of them is wrong.
+        if (askedForTheKey)
+            await keepSlot(address, vdk);
+    }
+    catch (err) {
+        if (!version) {
+            // The key is already on their screen, and the vault it was minted for
+            // does not exist. Said plainly, because the alternative is someone
+            // filing a key that opens nothing and trusting it for years. A re-run
+            // mints a new one, which is correct — and only correct if they know to
+            // discard this one.
+            process.stdout.write('\nThe backup did NOT complete, so the recovery key above was never used\n' +
+                'and opens nothing. Discard it. Running this command again will show you\n' +
+                'a new key.\n\n');
+        }
+        throw err;
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+// The key epochs the bundle declares, for the entry's binding. This is the only
+// part of the bundle the cloud side reads: everything else is carried opaquely
+// and handed back to the OSS unlock path, so the bundle's format stays theirs.
+function bundleKeyIds(bundle) {
+    try {
+        const parsed = JSON.parse(bundle.toString('utf8'));
+        const ids = (parsed.identities ?? [])
+            .map((i) => i.key_id)
+            .filter((k) => typeof k === 'string' && k !== '');
+        if (ids.length === 0)
+            throw new Error('no key ids');
+        return ids;
+    }
+    catch {
+        // Refuse rather than record an entry that binds nothing. A backup whose
+        // entry cannot say which epochs it holds is a backup nobody can reason
+        // about at restore time.
+        throw new Error('the handoff bundle does not declare any key epochs; refusing to file it ' +
+            'in the vault without them');
+    }
+}
+// `agmsg-cloud recovery restore <team>` — pull the current version, open it with the
+// recovery key, and hand the bundle to the OSS unlock path.
+export async function cmdVaultRestore(config, args) {
+    ensurePreflight(preflight(config.scriptsDir, NEEDS.vaultRestore));
+    const client = new CourierClient(config);
+    const binding = await remoteBinding(config.scriptsDir, args.team);
+    const { identity, version } = await readAccountVault(client);
+    if (!version) {
+        throw new Error('this account has no recovery vault yet — nothing to restore from');
+    }
+    // The slot first here too. Restore is the disaster path, so most of the time
+    // it runs on a machine that has no slot and the key is typed — but a machine
+    // that HAS one is a machine that has already proven it holds this vault's key,
+    // and asking it for the recovery key anyway would be asking for the one secret
+    // this design exists to keep filed away.
+    const { vdk, usedRecoveryKey } = await vdkForVault(identity, version, args.team);
+    const opened = openVaultWithVdk(identity, version, vdk);
+    // One vault, one key, whichever team was asked for: the container is opened
+    // as a whole and the team is selected from it.
+    const entry = selectTeam(parseContainer(opened.content), {
+        serverInstanceId: binding.serverInstanceId,
+        teamId: binding.teamId,
+    });
+    // Straight from the AEAD output into the OSS import, with no file in between.
+    // Writing it out first — even 0600 — would mean handing over a path, and a path
+    // can be made to point at other bytes after we vouched for these ones.
+    await unlockAuthenticatedBundle(config.scriptsDir, args.team, Buffer.from(entry.bundle, 'base64'));
+    process.stdout.write(`unlocked team '${args.team}' from the account vault, revision ${opened.revision}\n`);
+    // A restore that typed the key is the moment this machine first holds the
+    // vault's data key. Keeping a slot now is what stops the NEXT command on this
+    // replacement machine from asking for the key again — which is the whole
+    // complaint the slot exists to answer.
+    //
+    // Only when the key was typed: if the slot answered, one already exists at
+    // this address and saving would mint a second KEK for no reason.
+    if (usedRecoveryKey) {
+        await keepSlot(slotAddress(identity, version.vault_id, version.recovery_generation), vdk);
+    }
+}

package/dist/src/commands/watch.js

@@ -0,0 +1,47 @@
+import { CourierClient } from '../api.js';
+import { shellArg } from '../shell-arg.js';
+// (a) Bridge waiting enrollment requests to the operator's attention: poll the
+// approver-facing list and print one line per NEW request, so it can be surfaced
+// through the agmsg monitor. Runs until interrupted; only the first sighting of a
+// request id is emitted.
+//
+// It deliberately does NOT print a code. At this point there is no code to
+// print: the requester has published only a digest, and the value it hides is
+// not revealed until an approver has committed. Anything shown here would have
+// to be invented, and a code that appears before the ceremony has run is exactly
+// the thing a user must never learn to accept.
+export async function cmdWatch(config, args, deps = {}) {
+    const client = new CourierClient(config);
+    const interval = args.intervalMs ?? 15_000;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const seen = new Set();
+    while (!deps.signal?.aborted) {
+        let live = [];
+        try {
+            live = await client.listEnrollments();
+        }
+        catch (err) {
+            process.stderr.write(`poll failed: ${err.message}\n`);
+        }
+        for (const req of live) {
+            // Only requests still waiting for an approver to commit. One already in
+            // flight belongs to whoever is running `approve`, and announcing it again
+            // would invite a second key holder to start a competing ceremony.
+            if (req.status !== 'requester_committed')
+                continue;
+            if (seen.has(req.id))
+                continue;
+            seen.add(req.id);
+            process.stdout.write(
+            // The id is the server's, not ours, and it lands in an argument
+            // position of a line written to be pasted. Quoted for that reason
+            // rather than because a UUID needs it: what makes a value safe here is
+            // where it goes, not what it happens to contain today.
+            `enrollment request ${req.id} "${req.label}" — run \`agmsg-cloud approve <team> ${shellArg(req.id)}\` ` +
+                `to compare codes with them (expires ${req.expires_at})\n`);
+        }
+        if (deps.signal?.aborted)
+            break;
+        await sleep(interval);
+    }
+}

package/dist/src/config.js

@@ -0,0 +1,34 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readCredential } from './credentials.js';
+// The two environment values are ALL-OR-NOTHING. Accepting one and filling the
+// other from the store would combine a stored secret with an endpoint chosen
+// elsewhere — that is not an override, it is sending this machine's capability
+// secret to a host it was never minted for. Mixing is refused; replacing wholesale
+// is not (CI and headless runs are exactly that).
+function fromEnv(env) {
+    const baseUrl = env.AGMSG_CLOUD_ENDPOINT;
+    const secret = env.AGMSG_CLOUD_SECRET;
+    if (baseUrl && secret)
+        return { endpoint: baseUrl, secret };
+    if (baseUrl || secret) {
+        const given = baseUrl ? 'AGMSG_CLOUD_ENDPOINT' : 'AGMSG_CLOUD_SECRET';
+        const missing = baseUrl ? 'AGMSG_CLOUD_SECRET' : 'AGMSG_CLOUD_ENDPOINT';
+        throw new Error(`${given} is set but ${missing} is not. Set both or neither: a stored secret is only ever sent to the endpoint it was minted for.`);
+    }
+    return null;
+}
+// Where the OSS scripts live, resolved WITHOUT a credential.
+//
+// `connect --preflight` is a dry run whose whole purpose is to be usable before
+// anything is set up, so it must not be refused for not being signed in.
+export function resolveScriptsDir(env = process.env) {
+    return env.AGMSG_SCRIPTS_DIR ?? join(homedir(), '.agents', 'skills', 'agmsg', 'scripts');
+}
+export function loadConfig(env = process.env) {
+    const resolved = fromEnv(env) ?? readCredential(null, env);
+    if (!resolved) {
+        throw new Error('not signed in on this machine — run `agmsg-cloud login --endpoint <url>` first');
+    }
+    return { baseUrl: resolved.endpoint, secret: resolved.secret, scriptsDir: resolveScriptsDir(env) };
+}