agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/commands/login.js

@@ -0,0 +1,334 @@
+import { DEFAULT_ENDPOINT, armEnterToOpen, verificationUrlIsSafe, } from '../browser.js';
+import { isOrgAddress, originOf, readCredential, writeCredential } from '../credentials.js';
+import { settleMachineName, validateMachineName } from '../machine-name.js';
+// `login` — the device-authorization flow, from this machine's side.
+//
+// It is the one subcommand that runs with no credential, so it takes its
+// endpoint as a flag and everything else from the server's own response. The
+// ordering below is the contract, not a preference: the capability URL is
+// written to disk BEFORE activation, because a credential minted but never
+// durably written is exactly the crash the provisional/activate split exists to
+// survive.
+// Must agree with the server's mint (edge/capability.ts). The secret is pulled
+// out of the capability URL's last path segment, so a response that does not
+// carry the expected shape is refused rather than stored: a wrong value here
+// would be sent as this machine's Bearer credential on every later command.
+const SECRET_RE = /^agsy_[a-f0-9]{8}_[A-Za-z0-9_-]{43}$/;
+// The binary is `agmsg-cloud`, and the approval screen shows the name the
+// SERVER holds for this client id — so the id the CLI sends is what decides
+// whether the person sees "agmsg CLI" (a different program, which never does
+// this login) or "agmsg-cloud CLI". Reported from a real approval screen.
+//
+// The server allowlist carries both ids during the swap (#103), so this side
+// can move without an ordering constraint; the old entry is removed afterwards.
+const CLIENT_ID = 'agmsg-cloud-cli';
+// Terminal outcomes get the server's own reason back, verbatim and named: each
+// one is a different thing for the operator to do, and collapsing them into
+// "login failed" throws that away.
+const TERMINAL = {
+    access_denied: 'the request was denied in the browser',
+    expired_token: 'the code expired before it was approved — run login again',
+    machine_exists: 'that org already runs a machine under this name — run login again with a different --machine-name, or remove the existing machine first',
+    over_machines_cap: "this org is at its machine limit — remove a machine or move to a plan that allows more",
+    payment_required: 'this org has no active subscription — start one in the console, then run login again',
+};
+function secretFromCapabilityUrl(capabilityUrl) {
+    const segments = new URL(capabilityUrl).pathname.split('/');
+    const secret = segments[segments.length - 1] ?? '';
+    if (!SECRET_RE.test(secret)) {
+        throw new Error('the server returned a capability URL in an unrecognised shape; refusing to store it');
+    }
+    return secret;
+}
+// A network error is fatal for the request that OPENS the grant — there is
+// nothing to wait for yet — but not for the poll that follows it. That poll
+// runs for as long as the operator takes to reach their browser, over a
+// connection the server is free to close when it goes idle, and from here an
+// idle-timeout reset is indistinguishable from a real outage. Ending a login on
+// one discards a code that is still valid and still approvable.
+class Unreachable extends Error {
+    code;
+    constructor(host, code) {
+        super(`could not reach ${host}${code ? ` (${code})` : ''} — check the address and your network, or pass --endpoint if you run your own agmsg cloud`);
+        this.code = code;
+        this.name = 'Unreachable';
+    }
+}
+export async function cmdLogin(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? (() => Date.now());
+    const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, '');
+    // The flag, validated, before anything is asked. `settleMachineName` returns
+    // it verbatim when it is given, so nothing below needs the prompt to know
+    // what the caller wants — and a malformed value should be refused before the
+    // command starts talking to a server.
+    const asked = opts.machineName === undefined ? undefined : validateMachineName(opts.machineName);
+    // Said out loud on EVERY run, default or not. A default is convenient, and
+    // the thing it takes away is the moment the operator typed the destination —
+    // so the destination is printed instead. Nobody should have to guess which
+    // server their machine is about to be registered with.
+    process.stdout.write(`Connecting to ${new URL(endpoint).host}\n`);
+    const post = async (path, body, bearer) => {
+        try {
+            return await fetchImpl(`${endpoint}${path}`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    ...(bearer === undefined ? {} : { authorization: `Bearer ${bearer}` }),
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            // Node's network failures surface as a bare "fetch failed" with the cause
+            // buried. That is the first thing a new user sees when the host is wrong,
+            // down, or unreachable, and on its own it names neither the destination
+            // nor anything to do about it.
+            throw new Unreachable(new URL(endpoint).host, err.cause?.code);
+        }
+    };
+    // P1: the recovery this command's own error message promises must exist.
+    // Two crashes leave a credential on disk that the server has not been told
+    // about, or has: (a) the durable write landed but the activate never reached
+    // the server, and (b) it reached the server and the response was lost. Both
+    // are repaired by retrying the IDEMPOTENT activate with what is already
+    // stored, before opening a new grant — a fresh grant would instead collide
+    // with the machine name the stored credential is holding.
+    //
+    // Read BEFORE the machine name is asked for. The prompt used to run first, so
+    // a machine that was already signed in was asked to name itself and only then
+    // told the question had no bearing — and the asking is not a wasted
+    // keystroke, it is a claim. Two people read it as evidence that the stored
+    // credential had been deleted, and went looking for a file that was on disk
+    // the whole time (#193).
+    //
+    // rc.2 checked first. #169 moved the prompt to the top of the command to
+    // reuse the name on both screens; nothing in it was about ordering, so
+    // nothing looked at the ordering.
+    const stored = readCredential(originOf(endpoint), process.env);
+    if (stored && (asked === undefined || stored.machineName === asked)) {
+        const res = await post('/v1/device/activate', {}, stored.secret);
+        if (res.ok) {
+            process.stdout.write(`Already signed in as machine "${stored.machineName}".\n`);
+            return;
+        }
+        const code = await errorCode(res);
+        // 401 not_found / 410 revoked|expired: the credential is genuinely dead, so
+        // a fresh login is the right move (the machine name was freed with it).
+        // Anything else is the server failing, and starting a new grant on top of a
+        // credential that may still be live would be the wrong repair.
+        if (res.status !== 401 && res.status !== 410) {
+            throw new Error(`a credential for ${originOf(endpoint)} is stored but could not be activated (${res.status} ${code}) — not starting a new login on top of it`);
+        }
+    }
+    // Only now is the name needed: this run is opening a grant, so there really
+    // is a machine to name.
+    //
+    // Asked for, not assumed. The name is what an approver reads to tell one
+    // machine from another, and defaulting to the hostname without showing it is
+    // how two machines came to be called the same thing in production.
+    // --machine-name still wins outright; a terminal gets a pre-filled question;
+    // a headless run gets the hostname and is told so.
+    const machineName = await settleMachineName(opts.machineName, {
+        ...(opts.nameDeps ?? {}),
+    });
+    const codeRes = await post('/v1/device/code', {
+        client_id: CLIENT_ID,
+        scope: 'login',
+        machine_name: machineName,
+    });
+    if (!codeRes.ok) {
+        const code = await errorCode(codeRes);
+        throw new Error(`could not start login: ${codeRes.status} ${code}`);
+    }
+    const grant = (await codeRes.json());
+    process.stdout.write(`\nOpen this page and check the code matches:\n\n`);
+    process.stdout.write(`  ${grant.verification_uri_complete}\n\n`);
+    process.stdout.write(`  code:    ${grant.user_code}\n`);
+    process.stdout.write(`  machine: ${machineName}\n\n`);
+    // Armed, never awaited: an approval done from a phone, or from a URL typed by
+    // hand, must still be noticed — so the poll below runs whether or not any key
+    // is ever pressed. `disarm` is bound to every exit path, because a live stdin
+    // listener would hold the process open after login has already finished.
+    const opener = (opts.armOpener ?? armEnterToOpen)(grant.verification_uri_complete, endpoint);
+    process.stdout.write(`Waiting for approval — nothing is granted until you approve it.\n`);
+    try {
+        return await pollUntilDecided(grant, {
+            post,
+            sleep,
+            now,
+            endpoint,
+            armOpener: opts.armOpener ?? armEnterToOpen,
+        });
+    }
+    finally {
+        opener.disarm();
+    }
+}
+async function pollUntilDecided(grant, ctx) {
+    const { post, sleep, now, endpoint, armOpener } = ctx;
+    // The poll is single-flight by construction: one loop, one request in flight.
+    // A concurrent second poll on the same grant would revoke the credential the
+    // first poll received.
+    let intervalMs = Math.max(grant.interval, 1) * 1000;
+    const deadline = now() + grant.expires_in * 1000;
+    for (;;) {
+        if (now() >= deadline) {
+            throw new Error('the code expired before it was approved — run login again');
+        }
+        await sleep(intervalMs);
+        let res;
+        try {
+            res = await post('/v1/device/token', {
+                device_code: grant.device_code,
+                client_id: CLIENT_ID,
+            });
+        }
+        catch (err) {
+            // Keep waiting. The grant's own expiry is the deadline that ends this
+            // loop; a dropped connection is not evidence that anything is wrong with
+            // it. Measured against a control plane that never restarted: the process
+            // was up throughout and one keep-alive connection was closed.
+            if (err instanceof Unreachable) {
+                // Said out loud rather than swallowed: an operator watching a long wait
+                // should see that contact was lost and regained, not silence.
+                process.stdout.write(`  (lost contact with the server, still waiting)\n`);
+                continue;
+            }
+            throw err;
+        }
+        if (res.ok) {
+            const body = (await res.json());
+            // Checked, not cast. `org` is half the storage key, and a cast turns a
+            // missing field into `undefined` — which would key this credential under
+            // a literal "undefined" and put it in the way of the next real one. A
+            // server that does not send it is a server this build cannot store a
+            // credential for, and saying so is better than inventing a slot.
+            const issued = {
+                capability_url: String(body['capability_url'] ?? ''),
+                machine_name: String(body['machine_name'] ?? ''),
+                org: typeof body['org'] === 'string' ? body['org'] : '',
+            };
+            if (!issued.capability_url || !issued.org) {
+                throw new Error('the server answered without the fields this needs (capability_url, org) — it may be older than this CLI');
+            }
+            // Present is not the same as usable. `org` becomes half a storage key,
+            // and the key's delimiter is a space on the grounds that an org address
+            // cannot contain one — so a value like `x`, or one carrying a space or a
+            // newline, does not fail loudly. It writes a slot under a key nothing
+            // will look up again. Checked here so nothing durable happens first, and
+            // checked again in `keyFor` so a future caller cannot route around this.
+            if (!isOrgAddress(issued.org)) {
+                throw new Error('the server answered with an org address this build does not recognise — nothing was stored');
+            }
+            return finish(issued, endpoint, post);
+        }
+        const body = await errorBody(res);
+        const code = body.code;
+        if (code === 'authorization_pending')
+            continue;
+        if (code === 'slow_down') {
+            // The server's own backoff. Honouring it is what keeps a slow approval
+            // from turning into a rate-limit refusal.
+            intervalMs += 5000;
+            continue;
+        }
+        if (code === 'over_machines_cap') {
+            // Not a generic refusal: the operator is one upgrade away, and the
+            // numbers to decide with came back with the 403.
+            throw new Error(atMachineLimit(body, grant, endpoint, armOpener));
+        }
+        const explained = TERMINAL[code];
+        throw new Error(explained ? `login stopped: ${explained}` : `login failed: ${res.status} ${code}`);
+    }
+}
+async function finish(issued, endpoint, post) {
+    const secret = secretFromCapabilityUrl(issued.capability_url);
+    // Durable write FIRST. If the process dies between here and activate, the
+    // credential is on disk and the machine can be activated by running login
+    // again; the reverse order loses the only copy of the secret.
+    //
+    // The org comes from the token response because it is decided while this
+    // process is polling — the approver picks it in the console. It is half the
+    // storage key: without it, signing in to a second org on this host would
+    // overwrite the first org's secret.
+    writeCredential({
+        endpoint: originOf(endpoint),
+        org: issued.org,
+        secret,
+        capabilityUrl: issued.capability_url,
+        machineName: issued.machine_name,
+    });
+    const res = await post('/v1/device/activate', {}, secret);
+    if (!res.ok) {
+        const code = await errorCode(res);
+        throw new Error(`the credential was saved but could not be activated (${res.status} ${code}) — run login again`);
+    }
+    process.stdout.write(`\nSigned in as machine "${issued.machine_name}".\n`);
+    process.stdout.write(`Its sync address is saved on this machine; no token to copy.\n`);
+}
+async function errorCode(res) {
+    return (await errorBody(res)).code;
+}
+// A response body can be read once. Every caller that wants more than the code
+// — the machine-limit message wants the numbers beside it — has to come
+// through here, or the second read finds an already-consumed stream and the
+// facts vanish silently. (Found by the test that asserted the numbers.)
+async function errorBody(res) {
+    try {
+        const parsed = (await res.json());
+        return {
+            code: typeof parsed.error === 'string' ? parsed.error : 'unknown',
+            ...(typeof parsed.plan === 'string' ? { plan: parsed.plan } : {}),
+            ...(typeof parsed.limit === 'number' ? { limit: parsed.limit } : {}),
+            ...(typeof parsed.in_use === 'number' ? { inUse: parsed.in_use } : {}),
+        };
+    }
+    catch {
+        return { code: 'unknown' };
+    }
+}
+// "Your plan is at its machine limit" — with the plan, the numbers, and a way
+// to act on it.
+//
+// The old text named the limit and nothing else: not which plan, not how many
+// machines are in use, not where to change it. Someone reading it had to go
+// and find all three. The numbers come from the server's 403 rather than a
+// copy of the plan table here, so what is displayed and what is enforced
+// cannot drift apart.
+//
+// The Enter offer is the same one login already makes for the approval page,
+// deliberately: it declines to say "press Enter" where no keypress can arrive
+// and says what to do instead. Writing a second one here would recreate the
+// defect that one exists to fix.
+function atMachineLimit(body, grant, endpoint, armOpener) {
+    const lines = ['Cannot add this machine — your plan is at its machine limit.', ''];
+    if (body.plan !== undefined)
+        lines.push(`  plan:     ${body.plan}`);
+    if (body.limit !== undefined && body.inUse !== undefined) {
+        lines.push(`  machines: ${body.inUse} of ${body.limit} in use`);
+    }
+    // The console's own origin, taken from the address the SERVER gave for this
+    // login rather than assembled here — a self-hosted stack has its own, and a
+    // guess would send the operator somewhere that is not their console. Only
+    // the origin is used: the console selects Billing in the page, so there is
+    // no path to link to (see the report accompanying this change).
+    let consoleUrl = null;
+    try {
+        consoleUrl = new URL(grant.verification_uri).origin;
+    }
+    catch {
+        consoleUrl = null;
+    }
+    // The same check the approval page goes through. A URL we would not open is
+    // not one to put in front of someone either.
+    if (consoleUrl && verificationUrlIsSafe(consoleUrl, endpoint)) {
+        lines.push('', 'Upgrade in the console (open Billing there):', `  ${consoleUrl}`);
+        armOpener(consoleUrl, endpoint);
+    }
+    else if (consoleUrl) {
+        lines.push('', 'Upgrade in the console.');
+    }
+    return lines.join('\n');
+}

package/dist/src/commands/logout.js

@@ -0,0 +1,74 @@
+import { DEFAULT_ENDPOINT } from '../browser.js';
+import { originOf, removeCredentials } from '../credentials.js';
+import { clearRecordsForOrigin } from '../pending.js';
+/**
+ * The endpoint `logout` was asked for, or a refusal.
+ *
+ * The argv this command accepts is CLOSED — `[]`, or exactly
+ * `--endpoint <url>` — rather than filtered for the one flag it reads.
+ *
+ * Because it is destructive AND defaulted. Reading only `--endpoint` and
+ * ignoring the rest means `logout --endpont https://self.test` finds no flag,
+ * falls back to the hosted service, and deletes the production credential
+ * while the person believed they had named their own stack. So does
+ * `logout https://self.test`. Neither is an exotic input: they are a typo and
+ * a reasonable guess at the syntax.
+ *
+ * A command that removes a secret must not act on an argv it did not
+ * understand.
+ */
+export function logoutEndpoint(argv) {
+    const refuse = () => {
+        throw new Error('usage: agmsg-cloud logout [--endpoint <url>]');
+    };
+    if (argv.length === 0)
+        return undefined;
+    if (argv.length !== 2 || argv[0] !== '--endpoint')
+        return refuse();
+    const value = argv[1];
+    // A missing value would otherwise swallow the next token; there is no next
+    // token here, but the same shape (`--endpoint --force`) is what the flag
+    // reader elsewhere in this file guards against.
+    if (value.length === 0 || value.startsWith('--'))
+        return refuse();
+    try {
+        // Parsed here rather than at the point of deletion: an unparseable address
+        // should be refused before anything is read or removed.
+        void new URL(value);
+    }
+    catch {
+        return refuse();
+    }
+    return value;
+}
+export function cmdLogout(opts = {}) {
+    const env = opts.env ?? process.env;
+    const out = opts.out ?? ((text) => void process.stdout.write(text));
+    const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, '');
+    const origin = originOf(endpoint);
+    const removed = removeCredentials(origin, env);
+    const pending = clearRecordsForOrigin(origin, env);
+    if (removed.length === 0) {
+        // Not an error. "There was nothing to remove" is the state someone running
+        // this twice is in, and the state someone checking is in — and it is the
+        // same end state they asked for. Exiting non-zero would make a script that
+        // signs out defensively fail on the run where it worked.
+        out(`No credential stored for ${origin}.\n`);
+        if (pending > 0)
+            out(`Cleared ${pending} pending enrollment record(s).\n`);
+        return;
+    }
+    // Named, not counted. The person signing out is entitled to know which
+    // identity just left this machine — one host can hold credentials for
+    // several orgs, and "signed out" without saying whose is how someone
+    // discovers later that the wrong one went.
+    for (const credential of removed) {
+        out(`Signed out machine "${credential.machineName}" from ${origin} (org ${credential.org}).\n`);
+    }
+    if (pending > 0)
+        out(`Cleared ${pending} pending enrollment record(s).\n`);
+    // Said because the omission is the surprising part: someone who ran this to
+    // clean up a machine should not have to wonder whether their history went
+    // with it.
+    out(`This machine's device key and local team keys were not touched.\n`);
+}

package/dist/src/commands/pull.js

@@ -0,0 +1,80 @@
+import { spawnOssInherit } from '../oss-env.js';
+import { shellArg } from '../shell-arg.js';
+import { join } from 'node:path';
+import { CourierClient, isUuid } from '../api.js';
+import { originOf, readCredential } from '../credentials.js';
+import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
+function runInherit(command, args) {
+    return new Promise((resolve, reject) => {
+        // stdio inherited: `remote.sh pull` prints its own progress, and this is
+        // the slowest step of joining a second machine.
+        const child = spawnOssInherit(command, args);
+        child.on('error', reject);
+        child.on('close', (code) => resolve(code ?? 1));
+    });
+}
+export async function cmdPull(config, opts) {
+    ensurePreflight(preflight(config.scriptsDir, NEEDS.pull));
+    // The capability URL, not the control-plane endpoint: the sync gateway
+    // answers the former and never sees the latter.
+    const credential = readCredential(originOf(config.baseUrl));
+    if (!credential) {
+        throw new Error(`no stored credential for ${originOf(config.baseUrl)} — run \`agmsg-cloud login\` on this machine first`);
+    }
+    // `--team-id` skips the lookup, and with it every check the lookup's
+    // response boundary performs. Whatever is typed here goes to the OSS side
+    // as an identity, so it is checked in the one place left that can.
+    if (opts.teamId !== undefined && !isUuid(opts.teamId)) {
+        throw new Error(`--team-id must be a team UUID, not "${opts.teamId}"`);
+    }
+    const teamId = opts.teamId ?? (await resolveTeamId(config, opts));
+    process.stdout.write(`\nPulling "${opts.team}" onto machine "${credential.machineName}".\n`);
+    const run = opts.runner ?? runInherit;
+    const code = await run('bash', [
+        join(config.scriptsDir, 'remote.sh'),
+        'pull',
+        '--endpoint',
+        credential.capabilityUrl,
+        '--team-id',
+        teamId,
+        opts.team,
+    ]);
+    if (code !== 0) {
+        // The OSS script has already said what went wrong on this terminal.
+        throw new Error(`pull failed (remote.sh exited ${code})`);
+    }
+    // Says nothing about whether it is locked, because the OSS script now says
+    // that accurately for THIS machine: it decides on whether the current
+    // epoch's key is here, not on how many envelopes arrived, so it prints the
+    // locked line or the usable one. Restating it from here would either
+    // duplicate it or contradict it, and this side cannot tell which.
+    //
+    // What it adds is the route, which the OSS script no longer names because
+    // its route is not ours. Phrased as a condition rather than a claim, so it
+    // is true after either line above.
+    process.stdout.write(`\n"${opts.team}" is on this machine.\n`);
+    if (opts.nextStepsFromCaller !== true) {
+        process.stdout.write(`If it is still locked, \`agmsg-cloud sync ${shellArg(opts.team)}\` completes the key handoff:\n` +
+            'it asks a machine that already has the team, and the two of you compare eight digits.\n');
+    }
+}
+async function resolveTeamId(config, opts) {
+    const client = opts.client ?? new CourierClient(config);
+    const matches = await client.resolveTeamByName(opts.team);
+    if (matches.length === 0) {
+        // Named as what it is: this org has no such team. The alternative reading
+        // — that the team exists under someone else — is not ours to confirm or
+        // deny, and the answer is the same either way.
+        throw new Error(`no team named "${opts.team}" in this organization.\n\n` +
+            'Connect it from the machine that runs it first, or pass --team-id if you have it.');
+    }
+    if (matches.length > 1) {
+        // A name is not unique by construction, so this stops rather than picking.
+        // Pulling the wrong team writes another team's messages into this machine's
+        // store under a name the operator chose, which no later step would notice.
+        const ids = matches.map((m) => `  ${m.teamId}`).join('\n');
+        throw new Error(`"${opts.team}" is ambiguous — this organization has ${matches.length} teams with that name:\n\n${ids}\n\n` +
+            'Re-run with --team-id <id> to say which one.');
+    }
+    return matches[0].teamId;
+}