agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/index.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { loadConfig, resolveScriptsDir } from './config.js';
+import { cmdApprove } from './commands/approve.js';
+import { cmdConnect, cmdConnectPreflight } from './commands/connect.js';
+import { cmdFetch } from './commands/fetch.js';
+import { cmdSync } from './commands/sync.js';
+import { cmdLogin } from './commands/login.js';
+import { cmdLogout, logoutEndpoint } from './commands/logout.js';
+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';
+const USAGE = `agmsg-cloud — hosted agmsg from this machine
+
+  login                        sign this machine in; approve it in your own browser
+        [--endpoint <url>]     a self-hosted or development stack (default: the hosted service)
+        [--machine-name <n>]   the name this machine is registered under (default: hostname)
+
+  logout                       remove this machine's stored credential for the service
+        [--endpoint <url>]     the same address login used (default: the hosted service)
+
+  connect <team>               put a team this machine already runs onto the hosted service
+  connect --preflight          check what connect needs, without connecting anything
+
+  pull <team>                  (on a SECOND machine) take a team the first one already connected
+        [--team-id <id>]       when the name is ambiguous, or already known
+
+  sync <team>                  (on the NEW machine) join <team>: ask, wait for approval, take the team
+  request <label>              (on the NEW machine) ask to be added; prints a code to read to the approver
+  fetch <team>                 (on the NEW machine) unlock <team> from the approved bundle;
+                               it is matched against the snapshot your code authenticated
+  approve <team> [request-id]   (on a key-holding machine) approve the waiting request after the codes match
+  watch [--interval-ms <n>]    (on a key-holding machine) print pending requests as they arrive
+  recovery setup [team]        create this account's recovery key and back up every active
+                               team this machine's store reports; name one to back up
+                               only that team
+  recovery restore <team>      (on any approved machine) open the backup and unlock <team>
+  version                      the version of this CLI (also --version, -v)
+                               the OSS scripts it drives are reported by
+                               \`connect --preflight\`, which is a separate answer
+
+The recovery key is generated by \`recovery setup\` on the first run, shown once,
+and never stored anywhere. There is ONE for the account, not one per team — which
+is why it is not something to repeat each time a team is added. What one run
+covers is every active team THIS MACHINE's store reports, and it names them when
+it finishes; a team connected only on another machine is backed up by running it
+there. It is the only thing that opens the backup — if it is lost, so is the
+backup. After the first run, a machine with an OS secure store
+keeps a key slot and does not ask for it again; a machine without one asks every
+time, and says so. It can only be typed at a terminal: there is no flag and no
+environment variable for it.
+
+Environment (for CI and headless runs; \`login\` is the normal path):
+  AGMSG_CLOUD_ENDPOINT   base URL of the hosted edge
+  AGMSG_CLOUD_SECRET     this machine's capability secret
+
+Both or neither: a stored secret is only ever sent to the endpoint it was
+minted for, so one of these without the other is refused rather than mixed
+with what \`login\` saved.
+`;
+// A flag whose value is missing must not silently swallow the NEXT flag:
+// `login --endpoint --machine-name x` would otherwise send this machine's login
+// to an endpoint called "--machine-name".
+function flagValue(argv, flag) {
+    const i = argv.indexOf(flag);
+    if (i < 0)
+        return undefined;
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+        throw new Error(`${flag} needs a value (it was given none, or the next argument is another flag)`);
+    }
+    return value;
+}
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    // `loadConfig()` is resolved PER COMMAND, not up front: `login` is the one
+    // subcommand that runs before a credential exists, and a top-level call would
+    // refuse it before its branch was ever reached. Every other command resolves
+    // the same config it always did, one step later.
+    switch (cmd) {
+        // Answers for THIS binary only, and resolves no config: someone asking what
+        // they are running is often asking because something else refused, and a
+        // version that needs a working credential to print cannot be read at the
+        // moment it is wanted.
+        case 'version':
+        case '--version':
+        case '-v': {
+            // `name/version`, not `name version`. The space form is shaped exactly
+            // like an invocation of this binary, so it reads as though the version
+            // were the subcommand — and the printed-commands check says the same
+            // thing from the other side, since a line beginning `agmsg-cloud ` is
+            // 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`);
+            return;
+        }
+        case 'login': {
+            // No endpoint means the official deployment. The flag stays for
+            // self-hosted and development stacks; either way the destination is
+            // printed before anything is sent to it.
+            const endpoint = flagValue(rest, '--endpoint');
+            const machineName = flagValue(rest, '--machine-name');
+            return cmdLogin({
+                ...(endpoint === undefined ? {} : { endpoint }),
+                ...(machineName === undefined ? {} : { machineName }),
+            });
+        }
+        case 'logout': {
+            // Local only, and its own subcommand rather than a flag on `login`: the
+            // two do opposite things, and a flag that inverts a command is how
+            // someone signs out while meaning to sign in.
+            // Closed argv, not a filtered read: this removes a secret and defaults
+            // to the hosted service, so an argument it does not understand must not
+            // become "the default one".
+            const endpoint = logoutEndpoint(rest);
+            return cmdLogout(endpoint === undefined ? {} : { endpoint });
+        }
+        case 'connect': {
+            // The dry run resolves no credential: its job is to be usable before
+            // anything is set up.
+            if (rest.includes('--preflight'))
+                return cmdConnectPreflight(resolveScriptsDir());
+            const team = rest[0];
+            if (!team || team.startsWith('--')) {
+                throw new Error('usage: agmsg-cloud connect <team>   (or: agmsg-cloud connect --preflight)');
+            }
+            return cmdConnect(loadConfig(), { team });
+        }
+        case 'pull': {
+            const team = rest[0];
+            if (!team || team.startsWith('--')) {
+                throw new Error('usage: agmsg-cloud pull <team> [--team-id <id>]');
+            }
+            const teamId = flagValue(rest, '--team-id');
+            return cmdPull(loadConfig(), { team, ...(teamId === undefined ? {} : { teamId }) });
+        }
+        case 'request': {
+            const label = rest[0];
+            if (!label)
+                throw new Error('usage: agmsg-cloud request <label>');
+            return cmdRequest(loadConfig(), { label });
+        }
+        case 'sync': {
+            // The whole second-machine path. `request`, `fetch` and `pull` remain as
+            // their own commands — someone recovering a half-finished join still
+            // needs to run one of them alone — but nobody has to know that on a
+            // first machine.
+            const team = rest[0];
+            if (!team)
+                throw new Error('usage: agmsg-cloud sync <team> [--label <name>] [--team-id <uuid>]');
+            const label = flagValue(rest, '--label');
+            const teamId = flagValue(rest, '--team-id');
+            return cmdSync(loadConfig(), {
+                team,
+                ...(label === undefined ? {} : { label }),
+                ...(teamId === undefined ? {} : { teamId }),
+            });
+        }
+        case 'fetch': {
+            const team = rest[0];
+            if (!team)
+                throw new Error('usage: agmsg-cloud fetch <team>');
+            // `--confirm-digest` is no longer read. The digest is bound into the
+            // eight digits and recorded by `request` from the transcript it derived
+            // them over, so the bundle is checked against what the ceremony
+            // authenticated rather than against a string retyped from a phone call.
+            //
+            // Accepted and ignored rather than rejected: pasted instructions and
+            // scripts still carry it, and failing them would be a worse first
+            // impression than telling the truth about what happens now. It is said
+            // out loud, because a flag that is silently ignored is how someone keeps
+            // believing they are the check.
+            if (flagValue(rest, '--confirm-digest') !== undefined) {
+                process.stderr.write('--confirm-digest is no longer used, and was ignored.\n\n' +
+                    'The bundle is now checked against the snapshot your eight-digit code\n' +
+                    'authenticated, which this machine recorded when you compared it. Reading\n' +
+                    'the digest aloud is not needed and no longer decides anything.\n\n');
+            }
+            return cmdFetch(loadConfig(), { team });
+        }
+        case 'approve': {
+            // The id is optional. With one machine waiting — the ordinary case — the
+            // approver has nothing to copy from another screen, which is the point:
+            // the fewer values a person carries between machines, the fewer of them
+            // are the check. With more than one waiting it refuses and lists them,
+            // because which one is on the other end of the call is not knowable here.
+            const [team, requestId] = rest;
+            if (!team)
+                throw new Error('usage: agmsg-cloud approve <team> [request-id]');
+            return cmdApprove(loadConfig(), requestId ? { team, requestId } : { team });
+        }
+        case 'watch': {
+            const i = rest.indexOf('--interval-ms');
+            const intervalMs = i >= 0 && rest[i + 1] ? Number(rest[i + 1]) : undefined;
+            if (intervalMs !== undefined && (!Number.isFinite(intervalMs) || intervalMs < 1000)) {
+                // A positive floor: a zero/negative interval would busy-loop the poller.
+                throw new Error('--interval-ms must be a number >= 1000');
+            }
+            return cmdWatch(loadConfig(), intervalMs === undefined ? {} : { intervalMs });
+        }
+        // `recovery`, not `vault`. `vault put <team>` reads as filing a copy of
+        // something that already exists; the command MINTS the recovery key —
+        // the one thing that opens the backup, shown once and stored nowhere.
+        // A name that hides that is a name someone runs without reading.
+        case 'recovery': {
+            const [sub, team] = rest;
+            if (sub !== 'setup' && sub !== 'restore') {
+                // The two take different arguments, so one line covering both said the
+                // wrong thing about each: `setup` does not need a team and `restore`
+                // does. A usage message is read as the contract (raised in review).
+                throw new Error('usage: agmsg-cloud recovery setup [team]\n' +
+                    '       agmsg-cloud recovery restore <team>');
+            }
+            // `setup` takes no team in its ordinary form: the vault is the ACCOUNT's,
+            // so setting it up covers every connected team, and naming one made it a
+            // thing to repeat each time a team was added. A team may still be given,
+            // to add that one on its own. `restore` still requires one — it unlocks a
+            // specific team on this machine.
+            //
+            // The excuse rides inside the slot, so it cannot apply to anything else.
+            if (sub === 'restore' && !team) {
+                throw new Error(`usage: agmsg-cloud recovery ${ /* printed-commands: a subcommand name this file chooses, narrowed to 'setup' | 'restore' two lines up — not a value anyone supplies, and quoting it would print `recovery 'setup'` */sub} <team>`);
+            }
+            const config = loadConfig();
+            return sub === 'setup'
+                ? cmdVaultPut(config, team === undefined ? {} : { team })
+                : cmdVaultRestore(config, { team: team });
+        }
+        default:
+            throw new Error(`unknown command: ${cmd}\n\n${USAGE}`);
+    }
+}
+main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/src/ledger.js

@@ -0,0 +1,296 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readIfPresent, uniqueTempPath, withFileLock } from './filelock.js';
+// The local attempt ledger of spec §4.1.
+//
+// WHY A LOCAL LEDGER EXISTS AT ALL. An attacker who can relay the ceremony can
+// abort every attempt whose code does not match a value they guessed, and ask
+// the user to "try again". Each retry is a fresh eight-digit guess, so without a
+// bound the attacker eventually wins by repetition rather than by breaking
+// anything. Counting the attempts is what turns an eight-digit code into an
+// eight-digit code you only get five shots at.
+//
+// It has to be LOCAL because the server is inside the threat model. The server
+// keeps its own counters as defense in depth, but a malicious one can simply
+// ignore them, so those counters cannot be the bound. The same reasoning is why
+// nothing here consults the network, and why a new server-supplied request id
+// must never reset anything.
+//
+// It has to be DURABLE for the same reason: if restarting the CLI cleared the
+// count, "try again" would just mean "restart the tool".
+const WINDOW_MS = 24 * 60 * 60 * 1000;
+const MAX_ATTEMPTS = 5;
+// §4.1: the interception warning starts at the SECOND failure in a window.
+const WARN_AFTER_FAILURES = 2;
+/**
+ * A ledger scope: canonical server origin plus a fingerprint of the local
+ * identity that owns the budget.
+ *
+ * §4.1 gives the two roles DIFFERENT identities on purpose, so they get
+ * different functions below rather than one that callers must remember to feed
+ * correctly. The role is part of the domain tag as well, so the two can never
+ * collide even if a deployment somehow used the same string for both.
+ *
+ * The identity is domain-separated and truncated rather than hashed raw: the
+ * approver's identity is a credential, and a filename must not carry a bare
+ * prefix of a credential digest that could be matched against one computed
+ * elsewhere.
+ */
+function scopeFor(role, serverOrigin, identity) {
+    const origin = new URL(serverOrigin).origin;
+    const fingerprint = createHash('sha256')
+        .update(`agmsg-cloud-ledger-scope-v1\0${role}\0`)
+        .update(identity)
+        .digest('hex')
+        .slice(0, 16);
+    return `${createHash('sha256').update(origin).digest('hex').slice(0, 16)}-${role[0]}${fingerprint}`;
+}
+// A's scope: "canonical server origin plus the fingerprint of the local
+// capability URL". The capability secret is that URL's credential.
+export function approverLedgerScope(serverOrigin, capabilitySecret) {
+    return scopeFor('approver', serverOrigin, capabilitySecret);
+}
+// B's scope: "the same local device identity and canonical server origin". The
+// device public key is that identity — deliberately not the capability, because
+// a machine that re-authenticates must not thereby get a fresh budget.
+export function requesterLedgerScope(serverOrigin, devicePubkey) {
+    return scopeFor('requester', serverOrigin, devicePubkey);
+}
+export function ledgerPath(scope, env = process.env) {
+    const base = env['AGMSG_CLOUD_HOME'] ?? join(homedir(), '.agmsg-cloud');
+    return join(base, 'ledger', `${scope}.json`);
+}
+// A timestamp this code wrote: an ISO string that parses to a finite time and
+// round-trips. Date.parse('garbage') is NaN, and NaN silently drops an attempt
+// out of every window comparison — so an unvalidated timestamp is not a
+// cosmetic problem, it is a budget reset.
+function validTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms))
+        return false;
+    return new Date(ms).toISOString() === value;
+}
+function validAttempt(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const a = value;
+    if (!validTimestamp(a['startedAt']))
+        return false;
+    if (typeof a['ceremony'] !== 'string' || a['ceremony'].length === 0)
+        return false;
+    if (a['outcome'] !== null && a['outcome'] !== 'succeeded' && a['outcome'] !== 'failed') {
+        return false;
+    }
+    if (a['note'] !== undefined && typeof a['note'] !== 'string')
+        return false;
+    return true;
+}
+// Every field is checked, not just that the file is JSON.
+//
+// The earlier version only caught a parse failure, which meant a file that was
+// syntactically valid and semantically nonsense — `startedAt: "garbage"` — was
+// accepted and emptied the window. Rewriting one string was the cheapest
+// possible way around the limit this file exists to impose. "Unreadable" has to
+// mean "does not satisfy the shape", or the check is decoration.
+function load(path, scope) {
+    const raw = readIfPresent(path);
+    if (raw === null)
+        return { version: 1, scope, attempts: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`attempt ledger is unreadable: ${path}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`attempt ledger is unreadable: ${path}`);
+    }
+    const doc = parsed;
+    if (doc['version'] !== 1 || !Array.isArray(doc['attempts'])) {
+        throw new Error(`attempt ledger is unreadable: ${path}`);
+    }
+    // The scope is in the file AND in the filename; disagreement means the file is
+    // not this scope's, and inventing an empty one in its place would hand the
+    // caller a fresh budget.
+    if (doc['scope'] !== scope) {
+        throw new Error(`attempt ledger does not belong to this scope: ${path}`);
+    }
+    for (const attempt of doc['attempts']) {
+        if (!validAttempt(attempt)) {
+            throw new Error(`attempt ledger is unreadable: ${path}`);
+        }
+    }
+    return doc;
+}
+function save(path, ledger) {
+    mkdirSync(join(path, '..'), { recursive: true, mode: 0o700 });
+    chmodSync(join(path, '..'), 0o700);
+    // A per-process temp name. A shared `${path}.tmp` is written by every process
+    // updating this file, so two of them rename over each other and one update
+    // vanishes — which for a ledger means an attempt that was charged is not.
+    const tmp = uniqueTempPath(path);
+    writeFileSync(tmp, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+}
+function withinWindow(ledger, now) {
+    return ledger.attempts.filter((a) => now - Date.parse(a.startedAt) < WINDOW_MS);
+}
+// The pure part, so a caller already holding the lock does not try to take it
+// again. Re-entering would deadlock against itself.
+function budgetOf(ledger, now) {
+    const live = withinWindow(ledger, now);
+    const failures = live.filter((a) => a.outcome === 'failed').length;
+    const open = live.find((a) => a.outcome === null) ?? null;
+    const oldest = live[0];
+    return {
+        used: live.length,
+        remaining: Math.max(0, MAX_ATTEMPTS - live.length),
+        failuresInWindow: failures,
+        openAttempt: open,
+        nextAvailableAt: live.length >= MAX_ATTEMPTS && oldest
+            ? new Date(Date.parse(oldest.startedAt) + WINDOW_MS).toISOString()
+            : null,
+        shouldWarnAboutInterception: failures >= WARN_AFTER_FAILURES,
+    };
+}
+export function readBudget(scope, env = process.env, now = Date.now()) {
+    const path = ledgerPath(scope, env);
+    return withFileLock(path, () => budgetOf(load(path, scope), now));
+}
+/**
+ * Consume one attempt. MUST be called before the approver commitment leaves this
+ * machine (§4.1) — not after the reply, not on success.
+ *
+ * Charging on the reply would leave every network failure free, and "the server
+ * hung up" is something an attacker can produce at will. So the attempt is on
+ * the books before the bytes go out, and stays there whatever happens next.
+ */
+/**
+ * Consume one attempt for `ceremony`, or resume the one it already has.
+ *
+ * Resuming is not a loophole: the same ceremony means the same commitment going
+ * back out, which is one guess however many times the process died trying to
+ * finish it. Charging again would mean a crash loop spends the whole day's
+ * budget without a single completed comparison — and an attacker can cause
+ * crashes far more easily than they can guess eight digits.
+ *
+ * A DIFFERENT ceremony while one is open is still refused: §4.1 allows one
+ * nonterminal attempt per scope.
+ */
+export function consumeAttempt(scope, ceremony, env = process.env, now = Date.now(), 
+// True when this run would send a commitment this scope has ALREADY been
+// charged for — same request, same bytes. The caller establishes it from the
+// local reservation; see the note below for why that is the whole proof.
+sameCommitment = false) {
+    const path = ledgerPath(scope, env);
+    // The whole read-decide-write happens under the lock. Deciding outside it and
+    // writing inside would be no better than not locking at all: two invocations
+    // would each read a ledger with budget left, each conclude they may proceed,
+    // and each send a commitment — spending two guesses while the file records one.
+    return withFileLock(path, () => {
+        const ledger = load(path, scope);
+        const before = budgetOf(ledger, now);
+        if (before.openAttempt) {
+            if (before.openAttempt.ceremony === ceremony) {
+                return { ok: true, budget: before, resumed: true };
+            }
+            return { ok: false, reason: 'attempt_already_open', budget: before };
+        }
+        // One reservation is one contribution is one attempt.
+        //
+        // §4.1 charges the commitment leaving A. What matters is not whether the
+        // earlier run got its bytes out — that would need the server, and the
+        // budget must be able to refuse before a single request goes out. It is
+        // that the bytes THIS run would send are the same bytes: the reservation
+        // holds nonce, digest and commitment together and is reused whole, so a
+        // second run of the same ceremony re-sends one guess the ledger already
+        // records. Charging again would count one contribution twice.
+        //
+        // The entry is reopened rather than duplicated, keeping its place in the
+        // window. It loses its recorded failure, and that is the intended meaning:
+        // `failuresInWindow` drives the interception warning, which counts
+        // comparisons that ENDED wrong, and this one has not ended — the run
+        // reopening it will close it again, as succeeded or as failed. An attacker
+        // retrying gets a NEW enrollment and a new reservation, so those still
+        // count separately (raised in review).
+        const alreadyCharged = sameCommitment
+            ? withinWindow(ledger, now).find((a) => a.ceremony === ceremony)
+            : undefined;
+        if (alreadyCharged) {
+            alreadyCharged.outcome = null;
+            delete alreadyCharged.note;
+            save(path, ledger);
+            return { ok: true, budget: budgetOf(ledger, now), resumed: true };
+        }
+        if (before.remaining === 0)
+            return { ok: false, reason: 'budget_exhausted', budget: before };
+        ledger.attempts.push({ startedAt: new Date(now).toISOString(), ceremony, outcome: null });
+        // Pruned only on write, and only outside the window. Nothing removes an
+        // attempt because it succeeded or failed: §4.1 keeps both counted.
+        ledger.attempts = ledger.attempts.filter((a) => now - Date.parse(a.startedAt) < WINDOW_MS);
+        save(path, ledger);
+        return { ok: true, budget: budgetOf(ledger, now), resumed: false };
+    });
+}
+/**
+ * Close the open attempt. It stays counted either way — a success closes the
+ * attempt, it does not refund it.
+ */
+/**
+ * Close the attempt belonging to `ceremony`. It stays counted either way — a
+ * success closes the attempt, it does not refund it.
+ *
+ * Closing by ceremony rather than "the most recent open one" is what makes a
+ * resumed attempt safe: whoever finishes closes the entry that was actually
+ * paid for, not whichever happened to be last.
+ */
+export function closeAttempt(scope, ceremony, outcome, note, env = process.env, now = Date.now()) {
+    const path = ledgerPath(scope, env);
+    return withFileLock(path, () => {
+        const ledger = load(path, scope);
+        for (let i = ledger.attempts.length - 1; i >= 0; i--) {
+            const attempt = ledger.attempts[i];
+            if (attempt.outcome === null && attempt.ceremony === ceremony) {
+                attempt.outcome = outcome;
+                if (note !== undefined)
+                    attempt.note = note;
+                break;
+            }
+        }
+        save(path, ledger);
+        return budgetOf(ledger, now);
+    });
+}
+// What the user is told. Kept here so the wording cannot drift between the two
+// places that must show it (§4.1 requires the same warning from A and from B).
+export function renderBudgetWarning(budget) {
+    if (!budget.shouldWarnAboutInterception)
+        return '';
+    return [
+        '',
+        `  WARNING: ${budget.failuresInWindow} enrollment attempts have failed here in the`,
+        '  last 24 hours. Repeated failures are what interception looks like from the',
+        '  inside — someone relaying the ceremony has to make you retry until a code',
+        '  they guessed comes up. Before trying again, confirm out of band that the',
+        '  other machine really is the one you think it is.',
+        '',
+    ].join('\n');
+}
+export function renderBudgetExhausted(budget) {
+    return [
+        '',
+        '  Enrollment is blocked here: five attempts have been used in the last 24',
+        `  hours. The next attempt becomes available at ${budget.nextAvailableAt}.`,
+        '',
+        '  This limit is part of what makes an eight-digit code safe to rely on, so',
+        '  there is no override. Waiting is the intended response; clearing local',
+        '  security state is not part of enrolling a device.',
+        '',
+    ].join('\n');
+}

package/dist/src/machine-name.js

@@ -0,0 +1,90 @@
+import { hostname } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+// What this machine is called, and who gets to see it before it is used.
+//
+// The name is the ONLY thing that distinguishes one machine from another on
+// the approver's screen. The eight digits say the machine on the other end is
+// the one that started the ceremony; the name says WHICH machine that is. Two
+// entries reading `mbp2024` make the second question unanswerable, and the
+// approver's only honest move is to refuse a join that is probably fine.
+//
+// It happened in production, on a walkthrough: the same laptop, a second user
+// account, and both machines named for the host.
+//
+// Defaulting to the hostname is not the bug. Defaulting to it WITHOUT SHOWING
+// IT is: a collision is obvious the moment someone sees the name, and invisible
+// until an approver is staring at two identical rows.
+// The same class login.ts refused before this moved here, character for
+// character. Two validators for one field is how a name is accepted by the
+// prompt and then refused by the server after a browser approval was spent.
+const CONTROL_CHARS_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+/** The hostname, normalized the same way a typed name is. */
+export function defaultMachineName() {
+    return hostname().normalize('NFC').trim();
+}
+/**
+ * Check a name and return it, or say what is wrong with it.
+ *
+ * The same bounds the server applies (edge/capability.ts validMachineName), so
+ * a name this accepts is not refused after a browser approval has been spent.
+ */
+export function validateMachineName(name) {
+    const cleaned = name.normalize('NFC').trim();
+    if (cleaned.length < 1 || cleaned.length > 128) {
+        throw new Error(`machine name must be 1-128 characters (got ${cleaned.length})`);
+    }
+    if (CONTROL_CHARS_RE.test(cleaned)) {
+        throw new Error('machine name must not contain control characters');
+    }
+    return cleaned;
+}
+// Pre-filled, not merely suggested. `rl.write(prefill)` puts the default on the
+// input line where it can be edited or accepted with Enter — the operator sees
+// the actual value rather than a placeholder they have to retype to change.
+async function askAtTerminal(prompt, prefill) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = rl.question(prompt);
+        rl.write(prefill);
+        return await answer;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Settle this machine's name: use what was given, or ask, or say what was
+ * assumed.
+ *
+ * Three paths, and the third is why this is not just a prompt:
+ *
+ *   given      an explicit --machine-name. Used as-is, no question. Someone
+ *              who said what they wanted is not asked again.
+ *   a terminal nothing given, and someone is there. Ask, with the hostname
+ *              already typed in. This is the ordinary path.
+ *   no tty     nothing given, nobody there. Use the hostname AND SAY SO. CI
+ *              and headless runs must not hang on a question nobody can
+ *              answer — the same call `recovery setup` makes about the
+ *              recovery key — but a name chosen silently is how this got
+ *              missed in the first place, so the run reports what it used.
+ */
+export async function settleMachineName(given, deps = {}) {
+    if (given !== undefined)
+        return validateMachineName(given);
+    const out = deps.out ?? ((text) => void process.stdout.write(text));
+    const isTty = deps.isTty ?? (() => Boolean(process.stdin.isTTY && process.stdout.isTTY));
+    const fallback = defaultMachineName();
+    if (!isTty()) {
+        out(`No machine name given and no terminal to ask at — using "${fallback}".\n`);
+        return validateMachineName(fallback);
+    }
+    const ask = deps.ask ?? askAtTerminal;
+    out('\nThis name is what an approver sees when this machine asks to join a team,\n');
+    out('and it is the only thing that tells one machine from another there.\n\n');
+    const answer = await ask('Machine name: ', fallback);
+    // An empty answer is the default, not an error: someone who pressed Enter
+    // through a pre-filled line meant to accept it, and a cleared line means the
+    // same thing to anyone who is not reading the source.
+    const chosen = answer.trim().length === 0 ? fallback : answer;
+    return validateMachineName(chosen);
+}