agmsg-cloud 0.1.0-rc.7 → 0.1.0-rc.8

package/dist/src/commands/login.js

@@ -116,7 +116,7 @@ export async function cmdLogin(opts) {
     if (stored && (asked === undefined || stored.machineName === asked)) {
         const res = await post('/v1/device/activate', {}, stored.secret);
         if (res.ok) {
-            out(`Already signed in as machine "${stored.machineName}".\n`);
+            out(`Already signed in as machine "${stored.machineName}" in organization "${stored.org}".\n`);
             return;
         }
         const code = await errorCode(res);

package/dist/src/commands/request.js

@@ -9,6 +9,72 @@ import { originOf } from '../credentials.js';
 import { deviceIdentityPath } from '../paths.js';
 import { closeAttempt, consumeAttempt, readBudget, renderBudgetExhausted, renderBudgetWarning, requesterLedgerScope, } from '../ledger.js';
 import { attachRequestId, clearRecord, listResumableRequesterRecords, reserveRequesterNonce, } from '../pending.js';
+/**
+ * The one thing a long wait cannot say for itself: that it is the design.
+ *
+ * `login` learned this in #279 — an agent held a URL and a code for 42 seconds
+ * waiting for a blocking command to return, because nothing told it the block
+ * WAS the mechanism. These waits are longer: `login` waits for a browser the
+ * operator already has open, and these wait for a person on another machine.
+ *
+ * Written once and used at every wait, so the three cannot drift into saying
+ * different things about the same behaviour. What may be added to it is what
+ * stopping costs, and that is NOT the same at every wait — see below.
+ */
+function saysItBlocks() {
+    return '  This command will not return until then. That is expected, not a failure.\n';
+}
+/**
+ * What stopping costs, and it stops being free after the digits are shown.
+ *
+ * MEASURED, both of them, because the first version of this file asserted the
+ * resume in all three places and was wrong in one:
+ *
+ *   interrupted before the answer   the next run prints `resuming enrollment
+ *                                   <id>` and continues the same ceremony.
+ *                                   Budget unchanged: used:1 remaining:4.
+ *
+ *   interrupted at the LAST wait,   the row goes terminal while nothing is
+ *   and the approver then answers   watching. `GET /v1/enrollments` lists
+ *                                   NONTERMINAL rows only, so the stored
+ *                                   record matches nothing, the old attempt is
+ *                                   closed as failed, and the next run starts a
+ *                                   NEW ceremony. Measured: used:2 remaining:3
+ *                                   — one of five, spent.
+ *
+ * So the resume line belongs at the first two waits and is false at the third.
+ * Saying it there would promise a cheap retry for the one interruption that
+ * costs something.
+ */
+function stoppingIsCheap() {
+    return '  Leave it running — if you do stop it, run the same command again to resume.\n';
+}
+/**
+ * NOTHING HERE WARNS ABOUT A SECOND TERMINAL, and that is a refusal to guess
+ * rather than a finding.
+ *
+ * The console prompt says "do not start a second one in another terminal", and
+ * #344 asked whether that is true before repeating it. It was measured twice
+ * and the two measurements disagree:
+ *
+ *   an attempt opened under a commitment no run could plan
+ *                       -> `consumeAttempt` refuses with `attempt_already_open`
+ *                          — but that is not the branch a second terminal takes,
+ *                          because `request` looks for a resumable record first.
+ *                          A rigged input, and it agreed with the warning.
+ *
+ *   a first run interrupted mid-wait, then a second started
+ *                       -> once observed printing `resuming enrollment <id>`
+ *                          and carrying on at no cost; once observed starting a
+ *                          NEW ceremony instead. The two runs differed in their
+ *                          server double, and which difference decided it was
+ *                          not established.
+ *
+ * So this says nothing about second terminals in either direction. A warning
+ * has to be true to be worth a reader's attention, and so does a reassurance.
+ * What IS established is on `stoppingIsCheap` above: the cost of stopping, at
+ * each wait, measured.
+ */
 export async function cmdRequest(config, args, deps = {}) {
     const out = deps.out ?? ((text) => void process.stdout.write(text));
     const writeErr = deps.err ?? ((text) => void process.stderr.write(text));
@@ -179,14 +245,20 @@ export async function cmdRequest(config, args, deps = {}) {
     }
     const done = () => clearRecord({ role: 'requester', serverOrigin: config.baseUrl, key: record.commitmentHex }, env);
     try {
-        out('waiting for an approver to commit...\n');
+        out('\nwaiting for an approver to commit...\n');
+        out('  The next move is on the other machine, where someone runs `agmsg-cloud approve`.\n');
+        out(saysItBlocks());
+        out(stoppingIsCheap());
         await waitForStatus(client, requestId, 'both_committed', deps.waitOptions);
         // Safe to open now: the approver's contribution is fixed and cannot change.
         await client.submitOpening(requestId, {
             device_pubkey: pubkey,
             opening_nonce: record.nonceHex,
         });
-        out('waiting for the approver to open...\n');
+        out('\nwaiting for the approver to open...\n');
+        out('  Nothing to do here yet — the digits to compare appear when this returns.\n');
+        out(saysItBlocks());
+        out(stoppingIsCheap());
         const opened = await waitForStatus(client, requestId, 'opened', deps.waitOptions);
         // Derived here, from the two opened nonces. Nothing displayed below came
         // from the server as a code.
@@ -205,6 +277,22 @@ export async function cmdRequest(config, args, deps = {}) {
         // requirement that the requester counts failed and incomplete attempts, and
         // warns from the second failure, did nothing on this side. Wait for the
         // server to say which way it went.
+        // THE THIRD WAIT, and it said nothing at all — worse than the two the issue
+        // named, and the longest silence in the run.
+        //
+        // No line of its own, unlike the other two. What a reader has to do here is
+        // already on the screen directly above: `renderSasBlock` says the approving
+        // machine shows eight digits too, that they should check they are the same,
+        // and what each answer means. A copy of that here is the repetition #195
+        // removed from this very screen — a second copy of the one line that has to
+        // be read is how a reader learns to skim it. What was missing was not the
+        // instruction. It was that this blocks.
+        out('\nwaiting for the approver to answer...\n');
+        out(saysItBlocks());
+        // NOT `stoppingIsCheap()`. This is the one interruption that costs an
+        // attempt — see the note on that function for the measurement.
+        out('  Stopping here is the one that costs: if they answer while nothing is\n');
+        out('  watching, the next run starts over and spends one of five attempts.\n');
         const settled = await waitForStatus(client, requestId, 'consumed', deps.waitOptions);
         // What the eight digits authenticated, kept for `fetch`.
         //

package/dist/src/commands/sync.js

@@ -32,6 +32,39 @@ export async function cmdSync(config, opts) {
     const request = d.request ?? cmdRequest;
     const fetch = d.fetch ?? cmdFetch;
     const pull = d.pull ?? cmdPull;
+    const client = new CourierClient(config);
+    // BEFORE THE CEREMONY, because `request` spends one of five attempts before
+    // it posts the enrollment. The ceremony is org-scoped and cannot discover
+    // that the named team belongs to another org; leaving this to `pull` made a
+    // wrong-account run finish the human comparison, spend an attempt, and only
+    // then say the team was absent (#345).
+    //
+    // This lookup is scoped by the current credential on the control plane. A
+    // failure to answer is not absence, and ambiguity is not resolved here:
+    // neither state is permission to spend a ceremony on a guessed team.
+    let matches;
+    try {
+        matches = opts.teamId === undefined
+            ? await client.resolveTeamByName(opts.team)
+            : (await client.listTeams()).filter((team) => team.teamId === opts.teamId);
+    }
+    catch (err) {
+        out(`Not started: this account's organization could not be checked for "${opts.team}": ` +
+            `${err instanceof Error ? err.message : String(err)}\n` +
+            'No enrollment was started, so this costs none of your attempts.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (matches.length !== 1) {
+        out(matches.length === 0
+            ? `Not started: this account's organization has no team named "${opts.team}".\n`
+            : `Not started: this account's organization has more than one team named "${opts.team}".\n`);
+        out('Check `agmsg-cloud whoami`, then sign in to the organization that holds the team.\n');
+        out('No enrollment was started, so this costs none of your attempts.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const resolvedTeamId = matches[0].teamId;
     // The approver sees this, and they are looking for a machine they recognise.
     // A hostname is what a person calls their laptop; a uuid is what they read
     // aloud wrongly.
@@ -62,7 +95,7 @@ export async function cmdSync(config, opts) {
     // join; failing the join over a failed courtesy check would be the refusal
     // this deliberately is not.
     try {
-        const existing = await new CourierClient(config).listDevices();
+        const existing = await client.listDevices();
         // THIS MACHINE'S OWN ROW IS NOT A CLASH WITH ITSELF.
         //
         // The comparison was on label alone, so a machine already on the account —
@@ -162,9 +195,11 @@ export async function cmdSync(config, opts) {
     // It stayed hidden because the second machine in testing pointed at the first
     // machine's install, where the team was already present — so the second
     // machine's path had never actually been walked.
-    await pull(config, opts.teamId === undefined
-        ? { team: opts.team, nextStepsFromCaller: true }
-        : { team: opts.team, teamId: opts.teamId, nextStepsFromCaller: true });
+    await pull(config, {
+        team: opts.team,
+        teamId: resolvedTeamId,
+        nextStepsFromCaller: true,
+    });
     // And now the key, which opens what arrived above. Only reachable once the
     // server says the ceremony was approved — `request` waits for that, and
     // throws otherwise. The bundle is checked against the snapshot those digits

package/dist/src/index.js

@@ -11,7 +11,7 @@ import { cmdPull } from './commands/pull.js';
 import { cmdRequest } from './commands/request.js';
 import { cmdVaultPut, cmdVaultRestore } from './commands/vault.js';
 import { cmdWatch } from './commands/watch.js';
-import { packageVersion } from './version.js';
+import { packageInstall } from './version.js';
 const USAGE = `agmsg-cloud — hosted agmsg from this machine
 
   login                        sign this machine in; approve it in your own browser
@@ -40,7 +40,8 @@ const USAGE = `agmsg-cloud — hosted agmsg from this machine
   whoami                       which of this account's machines this one is —
                                its name, its organization, and the prefix the
                                console shows beside it
-  version                      the version of this CLI (also --version, -v)
+  version                      the version of this CLI, and the directory it is
+                               running out of (also --version, -v)
                                the OSS scripts it drives are reported by
                                \`connect --preflight\`, which is a separate answer
 
@@ -104,7 +105,21 @@ async function main(argv) {
             // one it must assume someone will paste. Written without naming a
             // version: an example that has to be bumped is a second place to bump,
             // which is the reason this command reads the manifest at all.
-            process.stdout.write(`agmsg-cloud/${packageVersion()}\n`);
+            //
+            // The directory follows on its own line because the version alone does
+            // not answer the question people ask this command. `npm i -g agmsg-cloud`
+            // can succeed while a copy another package manager put earlier on PATH is
+            // what runs, and nothing about that is an error: both installs are valid
+            // and the shell picks one. That happened here, and the two defects being
+            // chased were already fixed in the copy that was NOT running. Choosing
+            // for the user would mean deciding their PATH; saying which one answered
+            // costs one line and leaves the choice where it was.
+            //
+            // A path, not a command: this line must not read as something to paste,
+            // which is why it is not shaped like an invocation.
+            const install = packageInstall();
+            process.stdout.write(`agmsg-cloud/${install.version}\n`);
+            process.stdout.write(`running from ${install.directory}\n`);
             return;
         }
         // Beside `version` for the same reason it sits there: both answer a

package/dist/src/recovery-key.js

@@ -70,8 +70,8 @@ export function generateRecoveryKey() {
 // error rather than a silent drop, so a wrong key fails as a wrong key and not
 // as a mangled one.
 export function normalizeRecoveryKey(input) {
-    let cleaned = input
-        .trim()
+    const entered = input.trim();
+    let cleaned = entered
         .toUpperCase()
         .replace(/[\s-]/g, '');
     // The prefix is a label, not key material, and it is stripped by LENGTH
@@ -87,6 +87,17 @@ export function normalizeRecoveryKey(input) {
     if (cleaned.length === PREFIX_SYMBOLS + TOTAL_SYMBOLS && cleaned.startsWith('AGMSG')) {
         cleaned = cleaned.slice(PREFIX_SYMBOLS);
     }
+    // Locate a pasted label before diagnosing one character inside it. The
+    // prompt masks the input, so "unusable character: :" after a 50-character
+    // paste does not tell the operator where the colon was or what a key should
+    // look like. Length is the larger fact and can be checked without exposing
+    // the secret: the canonical form is 35 characters, while accepted spacing
+    // and grouping still reduce to exactly 25 key symbols (or 30 with AGMSG).
+    if (cleaned.length !== TOTAL_SYMBOLS) {
+        throw new Error(`that entry is ${entered.length} characters; a recovery key is 35 characters ` +
+            `in the form ${PREFIX}XXXXX-XXXXX-XXXXX-XXXXX-XXXXX ` +
+            `(${TOTAL_SYMBOLS} symbols without the prefix and separators)`);
+    }
     cleaned = cleaned
         .replace(/[IL]/g, '1')
         .replace(/O/g, '0')
@@ -95,9 +106,6 @@ export function normalizeRecoveryKey(input) {
         if (!ALPHABET.includes(ch))
             throw new Error(`recovery key contains an unusable character: ${ch}`);
     }
-    if (cleaned.length !== TOTAL_SYMBOLS) {
-        throw new Error(`recovery key must be ${TOTAL_SYMBOLS} symbols, got ${cleaned.length}`);
-    }
     // The check symbol, verified here rather than at the vault. Without it, a
     // mistyped key is indistinguishable from a wrong one until the AEAD refuses
     // it — which is at restore time, the moment there is no way back. Naming the

package/dist/src/slot-advice.js

@@ -14,12 +14,18 @@ export function adviseOnSlot(result, ctx) {
     switch (result.reason) {
         case 'no-slot':
             // The first backup on this machine, or the first after a re-issuance.
-            // Worth one line, because the next sentence asks for the recovery key and
-            // the person deserves to know why this time and not next time.
+            // Worth saying before the next sentence asks for the recovery key. Do
+            // not promise "once": knowing that the slot is absent is not knowing
+            // that this session may write its replacement. A headless macOS session
+            // can read the default keychain name and still have add-generic-password
+            // refused with errSecInteractionNotAllowed. That fact is learned only
+            // after the vault has opened, when saveDeviceSlot performs the write.
             return {
                 tone: 'note',
                 lines: [
-                    'this machine has no key slot for this vault yet, so the recovery key is needed once.',
+                    'this machine has no key slot for this vault yet, so the recovery key is needed now.',
+                    'After this succeeds, the CLI will try to keep a slot in the OS secure store. If this',
+                    'session cannot use that store, the recovery key will be needed every time.',
                 ],
             };
         case 'no-store':

package/dist/src/version.js

@@ -5,27 +5,23 @@ import { fileURLToPath } from 'node:url';
 // version — an identity, and the only thing that tells one package.json from
 // another while walking up a tree that may contain several.
 const PACKAGE_NAME = 'agmsg-cloud';
-// The version this build was published as.
-//
-// Read from the package's own `package.json` at runtime rather than baked into
-// a constant, because a constant is a second place to update and the one that
-// gets forgotten: a build that says the wrong version is worse than one that
-// says none, since the answer looks authoritative either way. npm always
-// includes package.json in a tarball, so it is there for a published install.
-//
-// Found by walking UP from this module rather than by a fixed relative path,
-// because the depth differs between the two places this file runs from:
-// `src/version.ts` sits one level under the package root, `dist/src/version.js`
-// sits two. A path correct in one is wrong in the other, and the one that would
-// be wrong is the published one.
-//
-// The walk answers only from a manifest that NAMES this package. Without that
-// check the first non-empty version above the module wins, and the installs
-// most likely to hit it are the broken ones — a package.json missing or
-// stripped of its version is exactly when a monorepo root, an npx cache entry,
-// or a parent workspace supplies its own. Reporting a stranger's version is the
-// failure this command exists to prevent, wearing the shape of a success.
-export function packageVersion(moduleUrl = import.meta.url) {
+/**
+ * The install this process is running out of: its version AND where it is.
+ *
+ * Both come from ONE walk, and that is the point rather than a convenience.
+ * `which agmsg-cloud` answers from PATH and a manifest answers from the module
+ * graph; when two package managers have both installed this tool, those are two
+ * different questions with two different answers, and pairing them would report
+ * a directory that need not be where the version came from. The directory
+ * returned here is the one whose `package.json` supplied the version, so the
+ * two cannot disagree.
+ *
+ * Node resolves a module's realpath before loading it, so a bin symlink — the
+ * usual shape of a global install — has already been followed by the time
+ * `import.meta.url` exists. What comes back is the store directory, which is
+ * the part that tells a pnpm global install from an npm one.
+ */
+export function packageInstall(moduleUrl = import.meta.url) {
     let dir = dirname(fileURLToPath(moduleUrl));
     const { root } = parse(dir);
     for (;;) {
@@ -41,7 +37,7 @@ export function packageVersion(moduleUrl = import.meta.url) {
         if (manifest?.name === PACKAGE_NAME) {
             const version = manifest.version;
             if (typeof version === 'string' && version !== '')
-                return version;
+                return { version, directory: dir };
             // Fail closed. This IS the package and it cannot say what it is; climbing
             // past would hand the question to whatever sits above, which is how a
             // broken install comes to announce a stranger's version.
@@ -55,3 +51,6 @@ export function packageVersion(moduleUrl = import.meta.url) {
     // guessed — see the note above.
     throw new Error(`cannot determine the installed version: no ${PACKAGE_NAME} package.json above this module`);
 }
+export function packageVersion(moduleUrl = import.meta.url) {
+    return packageInstall(moduleUrl).version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",
@@ -34,7 +34,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsx scripts/check-printed-commands.ts && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
     "prepack": "pnpm run build && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
-    "verify:published": "tsx scripts/verify-published.ts"
+    "verify:published": "tsx scripts/verify-published.ts",
+    "verify:shown-install": "tsx scripts/verify-shown-install.ts"
   },
   "dependencies": {
     "@agmsg-cloud/sas-core": "workspace:*",