agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/commands/approve.js

@@ -0,0 +1,392 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { createApproverCommitment, verifySasCommitment } from '@agmsg-cloud/sas-core';
+import { CourierClient, CourierError } from '../api.js';
+import { pickLiveRequest } from '../pick-request.js';
+import { CeremonyError, renderSasBlock, sasFromOpenedTranscript, waitForStatus } from '../ceremony.js';
+import { exportSnapshotDigest, keyHandoff, sealToRecipient, verifyHandoffDigest } from '../oss.js';
+import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
+import { approverLedgerScope, closeAttempt, consumeAttempt, readBudget, renderBudgetExhausted, renderBudgetWarning, } from '../ledger.js';
+import { approverRecordAgreesWithItself, clearRecord, loadApproverRecord, reserveApproverNonce, } from '../pending.js';
+import { SAS_PINNED } from '../sas.js';
+async function confirm(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${prompt} [y/N] `)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+// (b) A approves one enrollment.
+//
+// A commits to its own nonce BEFORE the requester reveals anything, so it cannot
+// pick a value that steers the code once it has seen the requester's key. That
+// ordering is the whole reason the comparison means something, and it is why
+// this command is a sequence of waits rather than a single call.
+//
+/**
+ * Find the request this approval is for, when the operator named none.
+ *
+ * Returns null after explaining itself, rather than throwing: none pending and
+ * several pending are both ordinary situations, and an operator who typed a
+ * two-word command deserves to be told which one they are in.
+ */
+async function resolveRequest(client, writeErr) {
+    // The claim IS the decision, and it is the server's: it settles the choice
+    // under a lock and records it, so the commitment that follows is bound to the
+    // request that was unambiguous when the choice was made. The listing below is
+    // only used to EXPLAIN a refusal — it never decides.
+    try {
+        return (await client.claimSoleLiveRequest()).requestId;
+    }
+    catch (err) {
+        if (!(err instanceof CourierError) || (err.code !== 'ambiguous' && err.code !== 'none')) {
+            throw err;
+        }
+    }
+    const picked = pickLiveRequest(await client.listEnrollments());
+    if (picked.kind === 'one') {
+        // The server refused and the list now shows one. That is not a
+        // contradiction to resolve by proceeding: the claim is the decision, and
+        // something changed between the two calls. Naming the id is what says
+        // which request the operator means.
+        writeErr('the request this would answer changed while it was being chosen.\n' +
+            'Re-run naming the id: `agmsg-cloud approve <team> <request-id>`.\n');
+        return null;
+    }
+    if (picked.kind === 'none') {
+        writeErr('nothing is waiting for approval on this account.\n\n' +
+            'The joining machine runs `agmsg-cloud sync <team>` first; this command\n' +
+            'answers the request that makes.\n');
+        return null;
+    }
+    // Named, not counted. The operator is the only one who knows which machine
+    // they are on the phone with, and they cannot use a number to tell.
+    const lines = picked.requests
+        .map((r) => `  ${r.id}  ${r.label}  (started ${r.created_at})`)
+        .join('\n');
+    writeErr(`${picked.requests.length} machines are waiting for approval:\n\n${lines}\n\n` +
+        'Which one is on the other end of your call cannot be decided from here.\n' +
+        'Re-run with the id: `agmsg-cloud approve <team> <request-id>`.\n');
+    return null;
+}
+// Approval IS the bundle upload: sealing needs this machine's key material, so
+// there is no server-side flag anyone could flip instead. The human comparison
+// is the only thing standing between a substituted key and real key history.
+export async function cmdApprove(config, 
+// `requestId` is optional: with no id, this finds the one live request and
+// refuses if there is any doubt about which one that is (see resolveRequest).
+args, deps = {}) {
+    // The ceremony ends in `key.sh handoff`; a missing install would surface
+    // only after both sides have read their codes aloud to each other.
+    ensurePreflight(preflight(config.scriptsDir, NEEDS.approve));
+    const out = deps.out ?? ((text) => void process.stdout.write(text));
+    const writeErr = deps.err ?? ((text) => void process.stderr.write(text));
+    const err = deps.err ?? ((text) => void writeErr(text));
+    const env = deps.env ?? process.env;
+    const ask = deps.ask ?? confirm;
+    const client = new CourierClient(deps.fetchImpl ? { ...config, fetchImpl: deps.fetchImpl } : config);
+    // Fail closed until the arc that pins this protocol is complete. Approval
+    // seals real key history to the requester's key on the strength of the code
+    // comparison, so it must not run while any part of that comparison is
+    // provisional.
+    if (!SAS_PINNED) {
+        writeErr('approval is disabled: the SAS ceremony is not fully pinned yet, so sealing ' +
+            'key history now would rest on a comparison that is not finished.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const scope = approverLedgerScope(config.baseUrl, config.secret);
+    // Checked before anything is read from the network. The budget is a local
+    // bound, and asking the server about a request this machine is not allowed to
+    // attempt both leaks the intent and invites a "just once more" retry loop
+    // against a server that is happy to allow it.
+    // Deciding which request this is costs nothing and can fail for reasons that
+    // are not the operator's — none pending, or two — and spending one of a small
+    // budget to discover that would punish someone for asking a question.
+    //
+    // The decision is the SERVER's, and it is taken here rather than at commitment
+    // time. §4.1 charges the send, not the reply: once the commitment bytes leave
+    // this machine the attempt is spent whatever comes back, so an ambiguity
+    // discovered by the commitment call could only be undone by this ledger
+    // trusting the server's account of its own behaviour — and the server is
+    // inside the threat model. A malicious one would answer every commitment with
+    // "ambiguous" and get unlimited attempts for free. So the claim happens
+    // BEFORE the charge, carries no commitment, and the commitment later only
+    // asks whether that claim still holds (raised in review).
+    const requestId = args.requestId ?? (await resolveRequest(client, writeErr));
+    if (requestId === null) {
+        process.exitCode = 1;
+        return;
+    }
+    // Keyed on the request, so retrying the SAME ceremony after a timeout resumes
+    // the attempt already paid for instead of buying a second one. The commitment
+    // that goes back out is the same commitment; that is one guess, not two.
+    // Established BEFORE any request goes out, so the budget can still refuse
+    // without contacting anyone. A reservation for this request means the
+    // commitment this run would send is the one already reserved — reused whole,
+    // byte for byte — so it is the guess the ledger already holds rather than a
+    // new one. A record that does not reproduce its own commitment is not
+    // evidence of anything and is treated as absent (raised in review).
+    const reserved = loadApproverRecord({ serverOrigin: config.baseUrl, requestId }, env);
+    const sameCommitment = reserved !== null && approverRecordAgreesWithItself(reserved);
+    const charged = consumeAttempt(scope, requestId, env, Date.now(), sameCommitment);
+    if (!charged.ok) {
+        if (charged.reason === 'budget_exhausted') {
+            writeErr(renderBudgetExhausted(charged.budget));
+        }
+        else {
+            writeErr('\n  Another enrollment attempt is still open on this machine. Finish or\n' +
+                '  cancel it before starting a second one — one comparison at a time is\n' +
+                '  what keeps a mismatch attributable to a single ceremony.\n\n');
+        }
+        process.exitCode = 1;
+        return;
+    }
+    out(renderBudgetWarning(charged.budget));
+    const fail = (note) => {
+        closeAttempt(scope, requestId, 'failed', note, env);
+        writeErr(renderBudgetWarning(readBudget(scope, env)));
+    };
+    const start = await client.getEnrollment(requestId);
+    // `opened` is here because an approver who has SEEN the digits and not yet
+    // answered is the most ordinary way to arrive at this command a second time:
+    // the codes are on screen, the terminal dies, and the ceremony is unfinished.
+    //
+    // §4.1 already charges that run an attempt ("cancellation after A commits
+    // ... consumes an attempt exactly like a completed comparison"), so refusing
+    // to resume does not save anything — it forces a NEW enrollment, which
+    // consumes a second. Five interruptions blocked enrollment for 24 hours. The
+    // ledger was always built for this (consumeAttempt is keyed on the request
+    // id); only the selection was not.
+    const resuming = start.status === 'opened';
+    if (!resuming && start.status !== 'requester_committed' && start.status !== 'both_committed') {
+        fail(`request was ${start.status}`);
+        writeErr(`request ${requestId} is ${start.status}; nothing to approve\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // The snapshot A will hand over, fixed BEFORE it commits (§3.2). It is the
+    // public key-state description, not the bundle: nothing carrying identity
+    // material is written until the human answers.
+    //
+    // Exported outside the reservation lock, because the lock is synchronous and
+    // this spawns a child. That is safe because of what happens below on a
+    // retry: an existing reservation is returned whole and THIS digest is
+    // discarded, so a second concurrent approve cannot swap in a snapshot of its
+    // own (raised in review).
+    const snapshotDir = mkdtempSync(join(tmpdir(), 'agmsg-approve-'));
+    let handoffDigestHex;
+    try {
+        handoffDigestHex = await exportSnapshotDigest(config.scriptsDir, args.team, join(snapshotDir, 'snapshot.json'));
+    }
+    finally {
+        // Removed on every path this process controls. A SIGKILL leaves a public
+        // snapshot in a directory only this user can enter, which the spec states
+        // rather than promises away.
+        rmSync(snapshotDir, { recursive: true, force: true });
+    }
+    // Reserved before the digest is posted, and REUSED on a retry — the nonce
+    // AND the digest together, since the commitment is over both. Minting a
+    // second nonce for a commitment the server already holds is
+    // indistinguishable, from the requester's side, from the substitution this
+    // ceremony detects; re-exporting a snapshot would do the same to the half
+    // the digest covers.
+    const record = reserveApproverNonce({ serverOrigin: config.baseUrl, requestId: requestId, handoffDigestHex }, (digestHex) => {
+        const made = createApproverCommitment(digestHex);
+        return {
+            commitmentHex: made.commitmentHex,
+            nonceHex: Buffer.from(made.approverNonce).toString('hex'),
+        };
+    }, env);
+    const done = () => clearRecord({ role: 'approver', serverOrigin: config.baseUrl, key: requestId }, env);
+    try {
+        // Same bytes on a retry, so this is idempotent server-side.
+        // The last argument says how this request was chosen. When the operator
+        // named no id, the server already settled which request this is — before
+        // the attempt was charged and before these bytes existed — so this asks it
+        // to check that claim still holds, not to decide again (raised in review).
+        // Whether the requester's opening matches the commitment it made. Shared so
+        // the two paths cannot drift, but CALLED at a different moment in each, and
+        // that difference is the security property: on the live path it must run
+        // BEFORE this machine reveals its own nonce. Folding both calls into one
+        // site after the reveal was a real regression — DRY moved a check across a
+        // boundary it exists to sit on.
+        const requesterOpeningVerifies = (t) => t.device_pubkey !== null &&
+            t.opening_nonce !== null &&
+            verifySasCommitment(t.commitment, t.device_pubkey, new Uint8Array(Buffer.from(t.opening_nonce, 'hex')));
+        const refuseOpening = async () => {
+            await client.abortEnrollment(requestId);
+            done();
+            fail('requester opening did not verify');
+            writeErr('the requester opening does not match its commitment; nothing was revealed ' +
+                'and the request has been ended\n');
+            process.exitCode = 1;
+        };
+        let full;
+        if (resuming) {
+            // Nothing is sent. The commitment and the opening are already on the
+            // server — this run re-reads what is there and re-derives the same SAS
+            // from it, which is what §4(2) describes A doing in the first place. No
+            // state transition happens here; the only call that moves the request is
+            // the one after the human answers.
+            full = await client.getEnrollment(requestId);
+            // Resuming means doing the display again, NOT skipping the checks.
+            //
+            // This one has no counterpart above because the live path had just sent
+            // the commitment and knew it. Here the transcript arrives from a server
+            // that is inside the threat model, so what it calls "the approver's
+            // commitment" is checked against what this machine actually committed —
+            // the durable reservation. A relay that swapped it would otherwise get
+            // this machine to display a SAS derived from someone else's contribution.
+            if (full.approver_commitment !== record.commitmentHex) {
+                await client.abortEnrollment(requestId);
+                done();
+                fail('stored approver commitment is not this machine\'s');
+                writeErr('the request no longer carries the commitment this machine made; nothing was ' +
+                    'revealed and the request has been ended\n');
+                process.exitCode = 1;
+                return;
+            }
+        }
+        else {
+            await client.submitApproverCommitment(requestId, record.commitmentHex, args.requestId === undefined);
+            out(`request "${start.label}" — waiting for it to open...\n`);
+            const opened = await waitForStatus(client, requestId, 'requester_opened', deps.waitOptions);
+            // BEFORE revealing anything. The server relayed these values; checking
+            // them against the commitment fixed earlier is what makes the relay
+            // untrusted rather than trusted — and it is worth nothing if this
+            // machine's nonce is already out.
+            if (!requesterOpeningVerifies(opened)) {
+                await refuseOpening();
+                return;
+            }
+            full = await client.submitApproverOpening(requestId, record.nonceHex, record.handoffDigestHex);
+        }
+        // The resume path checks here instead, because by then both openings are
+        // already on the server and there is nothing left to withhold. What it can
+        // still refuse is to DISPLAY a SAS derived from an opening that does not
+        // verify, which is what this stops.
+        if (resuming && !requesterOpeningVerifies(full)) {
+            await refuseOpening();
+            return;
+        }
+        // The key the bundle is sealed to, taken from the transcript that was just
+        // verified. Non-null by that verification; narrowed here so the sealing
+        // below reads it from the checked value rather than from a variable that
+        // happened to survive a branch.
+        const devicePubkey = full.device_pubkey;
+        if (devicePubkey === null) {
+            await refuseOpening();
+            return;
+        }
+        const sas = sasFromOpenedTranscript(full);
+        out(renderSasBlock(sas, 'approver'));
+        const matched = await ask('Do the codes match exactly?');
+        if (!matched) {
+            // A mismatch is a result, not an error to swallow: reporting it is what
+            // makes the attempt count, and an attacker's best move is a retry that
+            // costs the user nothing.
+            await client.abortEnrollment(requestId);
+            done();
+            // A mismatch is the attack showing itself. It costs an attempt precisely
+            // so that an attacker cannot ask the user to "just try again" for free.
+            fail('codes did not match');
+            out('not approved. Nothing was sent, and this request is closed.\n');
+            return;
+        }
+        const scratch = mkdtempSync(join(tmpdir(), 'agmsg-cloud-'));
+        try {
+            const bundleFile = join(scratch, 'handoff.bundle');
+            await keyHandoff(config.scriptsDir, args.team, bundleFile);
+            // The bundle's own digest, measured for the comparison below — not for
+            // anyone to read. It used to be printed here and confirmed by voice,
+            // which is what this branch removed; what it is FOR is checking that the
+            // bundle just generated is the snapshot committed to before the digits
+            // were compared.
+            //
+            // The value comes from the same verification the joiner's `unlock`
+            // performs, never recomputed here: two implementations of one digest
+            // eventually disagree, and the disagreement looks like "we both read the
+            // same digits and it still refused".
+            const digest = await verifyHandoffDigest(config.scriptsDir, args.team, bundleFile, join(scratch, 'verify'));
+            // §4(5): the bundle is checked against what was COMMITTED to, before
+            // anything is sealed. If the key state moved between the commitment and
+            // this moment, the bundle B would receive is not the one the digits
+            // attested. B refuses it on arrival either way — that is what keeps this
+            // fail-closed against a dishonest approver — but stopping here is what
+            // stops an honest one from uploading a bundle it can already see is
+            // wrong and handing B a failure it cannot act on (raised in review).
+            if (digest !== record.handoffDigestHex) {
+                await client.abortEnrollment(requestId);
+                done();
+                fail('the key state changed after the commitment');
+                writeErr('not approved: this team\'s key state changed between the commitment and now,\n' +
+                    'so the bundle no longer matches the code that was compared.\n\n' +
+                    'Nothing was sealed or uploaded. This request is closed — re-running\n' +
+                    '`agmsg-cloud approve` on it will not reopen it. The joining machine has to\n' +
+                    'run `agmsg-cloud request <label>` again, and this approval starts fresh\n' +
+                    'from a new snapshot.\n');
+                return;
+            }
+            // The 64-hex read-back is gone.
+            //
+            // It existed because nothing else connected what the two people compared
+            // to what the joining machine would accept: the joiner checked the
+            // bundle against a string its operator typed, so a person reading
+            // correctly WAS the check. That connection is now machine-made — the
+            // digest is bound into the eight digits, recorded by `request` from the
+            // transcript it derived them over, and `fetch` refuses any bundle that
+            // does not match it.
+            //
+            // So this asked a human to re-verify, by eye, something already verified
+            // by comparison of bytes. Two checks are not better than one when the
+            // weaker one trains people to skim: sixty-four characters read aloud is
+            // exactly the ritual someone starts approving without finishing.
+            //
+            // What is NOT gone is the check itself. §4(5) still compares the
+            // generated bundle's digest against the committed one above, and the
+            // joiner still recomputes on receipt and refuses a mismatch.
+            const sealed = await sealToRecipient(devicePubkey, readFileSync(bundleFile));
+            const { device_id } = await client.uploadBundle(requestId, {
+                operation_id: randomUUID(),
+                ciphertext: sealed.toString('base64'),
+            });
+            done();
+            // Closed, not refunded: §4.1 keeps a success counted in the window.
+            closeAttempt(scope, requestId, 'succeeded', undefined, env);
+            out(`approved; registered device ${device_id}\n`);
+        }
+        finally {
+            rmSync(scratch, { recursive: true, force: true });
+        }
+    }
+    catch (err) {
+        if (err instanceof CeremonyError) {
+            // A timeout keeps BOTH the pending record and the open ledger entry: the
+            // next run resends the same commitment, which is the same attempt. Closing
+            // it here was the bug — the record said "resume me" while the ledger said
+            // "that one is over", so resuming cost a second guess.
+            if (err.reason === 'timed_out') {
+                writeErr(`approval did not complete: ${err.message}\n`);
+                writeErr('  Run the same command again to resume it; this costs no further attempt.\n');
+                process.exitCode = 1;
+                return;
+            }
+            done();
+            fail(err.reason);
+            writeErr(`approval did not complete: ${err.message}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        // Even an unexpected error closes the attempt. The commitment is already
+        // out; leaving the ledger open would block every later attempt instead.
+        fail('unexpected error');
+        throw err;
+    }
+}