agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/pick-request.js

@@ -0,0 +1,56 @@
+// Which request an argument-free `approve` acts on.
+//
+// Its own function, and pure, because the rule it encodes is the one thing
+// that must not bend: a machine that picks for you is a machine that can
+// approve the wrong device while the person watching believes they approved
+// the one they were told about. The eight digits authenticate a device; they
+// do not tell you WHICH pending request you are answering, so choosing has to
+// be unambiguous before the ceremony starts rather than after.
+/**
+ * Statuses an approval can START from.
+ *
+ * NOT every status a request is alive in. `requester_opened` means this
+ * approver already committed and the other side has opened — a ceremony in
+ * flight, which `cmdApprove` refuses to begin because beginning it again would
+ * mean committing twice. Including it here selected a request that the very
+ * next call rejected, after an attempt had been charged: the operator paid for
+ * "nothing to approve" (raised in review).
+ *
+ * Resuming an interrupted ceremony IS this, and `opened` is here for it.
+ *
+ * That sentence used to say the opposite — that resuming "is done by naming the
+ * id". It was not true: naming the id still hit approve's status gate, which
+ * accepted neither `opened` nor anything past it, so the documented way out was
+ * closed. An approver who saw the digits and did not answer could not finish
+ * from any command, and the enrollment sat unanswerable until it expired.
+ *
+ * `opened` is selectable because it is still a live request awaiting exactly
+ * one thing: this machine's answer. It is not a second attempt — §4.1 charged
+ * the run that opened it, and the ledger is keyed on the request id so the
+ * resumed run continues that same attempt rather than buying another.
+ */
+const SELECTABLE = ['requester_committed', 'both_committed', 'opened'];
+/**
+ * Choose the one live request, or refuse.
+ *
+ * Never picks the newest, and never picks the first. Two people enrolling at
+ * once is an ordinary thing — a laptop and a phone, or a colleague starting
+ * while you are mid-flow — and in that moment the two requests are
+ * indistinguishable to everyone except the people holding the devices.
+ * Selecting silently would make the approver's screen say one thing and the
+ * requester's another, with the digits still matching, because the digits are
+ * about a device and not about a queue position.
+ *
+ * Expiry is not consulted here. A request whose window has closed is not live,
+ * and the server is what decides that; treating a locally-computed clock as
+ * authoritative would let a slow machine refuse a request the server would
+ * still accept, or the reverse.
+ */
+export function pickLiveRequest(transcripts) {
+    const live = transcripts.filter((t) => SELECTABLE.includes(t.status));
+    if (live.length === 0)
+        return { kind: 'none' };
+    if (live.length > 1)
+        return { kind: 'many', requests: [...live] };
+    return { kind: 'one', request: live[0] };
+}

package/dist/src/preflight.js

@@ -0,0 +1,257 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { platform } from 'node:process';
+// What `connect` needs before it starts, checked all at once.
+//
+// Everything here is reported together. Finding one missing thing, installing
+// it, and being told about the next one is the shape this exists to avoid — and
+// it is worse than it sounds, because the operator has already spent the
+// browser approval by the time `connect` runs.
+//
+// The OSS `remote.sh doctor` covers the same ground for the OSS CLI and
+// deliberately reports `age` as OPTIONAL: plain remote sync defaults to cipher
+// "none", so refusing without age would tell a new user they were unfit for a
+// feature they had not asked for. **That is correct there and wrong here.**
+// Hosted teams always connect with `--e2ee` (the gateway refuses plaintext with
+// `e2ee_required`), so on this path age is not optional at all. Shelling out to
+// doctor would print "optional" next to a prerequisite this command cannot run
+// without.
+// The installed agmsg's own provenance string, obtained through the accessor it
+// publishes rather than by reading its files: `version.sh` is the OSS side's
+// documented answer to "what is installed here", and reaching past it would
+// bind us to a layout that is not ours.
+//
+// Reported, not compared. The string is a git-describe (`v1.1.11-320-gfbc90db`)
+// for an install taken from a branch, and a plain tag for a released one — and
+// those two do not order against each other. The dogfood install measures as
+// `v1.1.11-320-…` while the released `v1.1.13` has no remote sync at all, so a
+// numeric floor would reject the only install that can currently connect.
+// Until there is a released version to compare against, this is shown for
+// diagnosis and nothing is gated on it.
+export function installedVersion(scriptsDir) {
+    try {
+        const out = execFileSync('bash', [join(scriptsDir, 'version.sh')], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Does the installed remote.sh offer `connect`? Asked of the script itself: run
+// with no arguments it prints its usage, which names the subcommands it has.
+//
+// This is capability detection, not version detection, and the difference is
+// the point — see the note above `installedVersion`.
+//
+// What is deliberately NOT probed: whether this install carries the fix for the
+// store-migration data-loss path. There is no way to ask a script "do you have
+// this guard" without reading its innards and guessing, and a check that cannot
+// really answer is worse than none — it reads as a guarantee. The release plan
+// covers it instead: the fix ships before remote sync is public.
+function remoteSupportsConnect(scriptsDir) {
+    try {
+        const out = execFileSync('bash', [join(scriptsDir, 'remote.sh')], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return /\bconnect\b/.test(out);
+    }
+    catch (err) {
+        // Usage goes to stderr and exits non-zero in some versions; that output is
+        // just as good an answer as a clean exit.
+        const e = err;
+        const text = `${String(e.stdout ?? '')}${String(e.stderr ?? '')}`;
+        return /\bconnect\b/.test(text);
+    }
+}
+function onPath(command) {
+    try {
+        // `command -v` through the shell would re-interpret the name; execFile with
+        // a fixed argv does not.
+        execFileSync(platform === 'win32' ? 'where' : 'which', [command], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Install lines follow the OSS doctor's, so an operator who has seen one is not
+// told something different by the other.
+const AGE_INSTALL = [
+    'macOS (Homebrew):    brew install age',
+    'Debian/Ubuntu:       sudo apt install age',
+    'Windows (winget):    winget install FiloSottile.age',
+    'See https://github.com/FiloSottile/age for other install methods.',
+];
+const NODE_INSTALL = [
+    'macOS (Homebrew):    brew install node',
+    'Debian/Ubuntu:       sudo apt install nodejs',
+    'Windows (winget):    winget install OpenJS.NodeJS',
+    'See https://nodejs.org for other install methods.',
+];
+const PYTHON_INSTALL = [
+    'macOS (Homebrew):    brew install python3',
+    'macOS (Xcode tools): xcode-select --install',
+    'Debian/Ubuntu:       sudo apt install python3',
+    'Windows (winget):    winget install Python.Python.3',
+];
+// Measured at the call sites, not inferred:
+//   connect        remote.sh connect (commands/connect.ts) + remote.sh status
+//                  via remoteTeamId
+//   recovery setup    remote.sh status via remoteTeamId + key.sh handoff via
+//                     keyHandoff
+//   recovery restore  remote.sh status via remoteTeamId + remote.sh unlock —
+//                     no key.sh
+//   fetch             remote-sync.sh verify-age-handoff via
+//                     verifyHandoffDigest + remote.sh unlock via unlockBundle
+//                     — no key.sh
+//   approve           key.sh handoff via keyHandoff + remote-sync.sh via
+//                     verifyHandoffDigest — no remote.sh
+//   pull              remote.sh pull (commands/pull.ts) — no key.sh: the team
+//                     arrives sealed and is opened by fetch or
+//                     recovery restore
+export const NEEDS = {
+    connect: { command: 'connect', scripts: ['remote.sh'], requireConnect: true },
+    vaultPut: { command: 'recovery setup', scripts: ['remote.sh', 'key.sh'] },
+    vaultRestore: { command: 'recovery restore', scripts: ['remote.sh'] },
+    fetch: { command: 'fetch', scripts: ['remote.sh', 'remote-sync.sh'] },
+    approve: { command: 'approve', scripts: ['key.sh', 'remote-sync.sh'] },
+    pull: { command: 'pull', scripts: ['remote.sh'] },
+    // sync runs request -> pull -> fetch, so it needs the UNION of what they
+    // need, checked once at the start. Derived from the entries above rather
+    // than listed again: a `sync` that probed less than the steps it runs would
+    // pass its check and then fail at the third one — after the ceremony had
+    // happened, the approver had been interrupted, and the attempt had been
+    // spent on a machine that could never have finished.
+    //
+    // `request` has no entry because it shells out to nothing; the ceremony is
+    // HTTP and local age. Adding one here would claim a requirement that does
+    // not exist.
+    sync: {
+        command: 'sync',
+        scripts: ['remote.sh', 'remote-sync.sh'],
+    },
+};
+// The tools follow from the scripts rather than being listed per command, so
+// a command cannot end up demanding a binary it never reaches:
+//   remote.sh       talks to the control plane through python3, and starts the
+//                   sync engine, which runs on node
+//   remote-sync.sh  is itself node
+//   any of them     handles age-encrypted key material; hosted teams are
+//                   always end-to-end encrypted, so age is required here even
+//                   though the OSS doctor reports it as optional (see above)
+function toolsFor(scripts) {
+    return {
+        node: scripts.includes('remote.sh') || scripts.includes('remote-sync.sh'),
+        python3: scripts.includes('remote.sh'),
+    };
+}
+export function preflight(scriptsDir, needs) {
+    const { command, scripts } = needs;
+    const requireConnect = needs.requireConnect ?? false;
+    const requirements = [];
+    // The scripts come first: without them nothing else matters, and the fix is
+    // a different kind of thing (install agmsg, or point AGMSG_SCRIPTS_DIR at it)
+    // than installing a binary.
+    const missingScripts = scripts.filter((s) => !existsSync(join(scriptsDir, s)));
+    // Present AND able to do the thing. A version number would be the obvious
+    // check and is the wrong one: `version.sh` returns a git-describe string, so
+    // the install that can connect measures as v1.1.11-320-g… while a released
+    // v1.1.13 without remote sync measures as newer. A numeric floor would reject
+    // the only install that works. So the capability is asked for directly.
+    const scriptsPresent = missingScripts.length === 0;
+    const canConnect = scriptsPresent && (!requireConnect || remoteSupportsConnect(scriptsDir));
+    requirements.push({
+        name: requireConnect
+            ? `agmsg with remote sync (in ${scriptsDir})`
+            : `agmsg ${scripts.join(', ')} (in ${scriptsDir})`,
+        ok: canConnect,
+        why: !scriptsPresent
+            ? `${command} runs ${missingScripts.join(' and ')}, and this machine has no copy there.`
+            : 'the agmsg installed here does not offer `remote.sh connect`, so it predates remote sync.',
+        install: [
+            'Install or update:   npx agmsg install',
+            'Elsewhere?           point AGMSG_SCRIPTS_DIR at that install\'s scripts directory.',
+        ],
+    });
+    const tools = toolsFor(scripts);
+    requirements.push({
+        name: 'age and age-keygen',
+        ok: onPath('age') && onPath('age-keygen'),
+        why: 'hosted teams are end-to-end encrypted, and the keys are generated with age. The server refuses messages that are not encrypted, so this is required rather than optional here.',
+        install: AGE_INSTALL,
+    });
+    if (tools.node) {
+        requirements.push({
+            name: 'node',
+            ok: onPath('node'),
+            why: 'the sync engine that carries messages to and from the server runs on node.',
+            install: NODE_INSTALL,
+        });
+    }
+    if (tools.python3) {
+        requirements.push({
+            name: 'python3',
+            ok: onPath('python3'),
+            why: 'remote.sh talks to the control plane through python3.',
+            install: PYTHON_INSTALL,
+        });
+    }
+    return {
+        requirements,
+        ok: requirements.every((r) => r.ok),
+        command,
+        agmsgVersion: canConnect ? installedVersion(scriptsDir) : null,
+    };
+}
+// The refusal in front of every command that shells out: one place decides how
+// a missing prerequisite reads, so it reads the same whichever command found
+// it.
+//
+// It takes the RESULT rather than calling `preflight` itself. A wrapper that
+// called it would reach the real check even where a test has replaced the
+// module's `preflight` — the internal call does not go through the module's
+// exports — and the suites would then depend on whether the machine running
+// them happens to have age, node and python3.
+export function ensurePreflight(checks) {
+    if (checks.ok)
+        return;
+    process.stdout.write(`\n${checks.command} cannot run yet:\n\n${formatPreflight(checks)}`);
+    throw new Error('prerequisites are missing');
+}
+// Printed the same way whether this was `--preflight` or the check in front of a
+// real connect, so an operator sees one format.
+export function formatPreflight(result) {
+    const lines = [];
+    for (const r of result.requirements) {
+        lines.push(`  ${r.ok ? '[x]' : '[ ]'} ${r.name}`);
+    }
+    if (result.agmsgVersion !== null) {
+        // Named as what it is. Calling it "agmsg 1.1.11" would invite the reader to
+        // compare it with a release number, which is the thing it cannot be
+        // compared with.
+        lines.push('');
+        lines.push(`  agmsg reports itself as: ${result.agmsgVersion}`);
+    }
+    const missing = result.requirements.filter((r) => !r.ok);
+    if (missing.length === 0) {
+        lines.push('');
+        lines.push(`Everything ${result.command} needs is here.`);
+        return `${lines.join('\n')}\n`;
+    }
+    for (const r of missing) {
+        lines.push('');
+        lines.push(`${r.name} is missing. ${r.why}`);
+        for (const line of r.install)
+            lines.push(`  ${line}`);
+    }
+    lines.push('');
+    // Every refusal says what comes next. Listing what is missing without saying
+    // how to resume leaves the operator where they started.
+    lines.push('Install what is listed above, then run the same command again.');
+    return `${lines.join('\n')}\n`;
+}