agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/authenticated-digest.js

@@ -0,0 +1,234 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, constants, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, chmodSync, rmSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * Identify the (credential, device identity) pair without storing either.
+ *
+ * The device key is in here because a ceremony authenticates a DEVICE. Under
+ * one capability that key can be regenerated, and then an old ceremony's
+ * record would sit in the same scope as the new identity's: the old digest
+ * would be applied to a bundle the new identity cannot decrypt, or the two
+ * would collide and refuse (raised in review). A record whose device key no longer
+ * exists on this machine is a record about a different machine-identity, and
+ * this is what says so.
+ */
+export function fingerprintScope(secret, devicePubkey) {
+    return createHash('sha256')
+        .update(Buffer.from('agmsg-cloud-authenticated-digest-scope-v2\0', 'ascii'))
+        .update(Buffer.from(secret, 'utf8'))
+        .update(Buffer.from('\0', 'ascii'))
+        .update(Buffer.from(devicePubkey, 'utf8'))
+        .digest('hex')
+        .slice(0, 32);
+}
+const HEX64 = /^[0-9a-f]{64}$/;
+const SCOPE_HEX = /^[0-9a-f]{32}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+// A file rewritten in place keeps the mode it already had, and a directory
+// someone created with a looser umask keeps that too. Both are repaired here
+// rather than trusted.
+function enforceMode(path, want) {
+    try {
+        if ((statSync(path).mode & 0o777) !== want)
+            chmodSync(path, want);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+function baseDir(env) {
+    return join(env.AGMSG_CLOUD_HOME ?? join(homedir(), '.agmsg-cloud'), 'authenticated');
+}
+// One file per settled ceremony rather than one per origin. Two of them is a
+// state this refuses to guess in (see readAuthenticatedDigests), and a single
+// file would make that state unrepresentable by overwriting — which is not the
+// same as it not happening.
+function pathFor(dir, origin, requestId) {
+    const key = Buffer.from(origin, 'utf8').toString('base64url');
+    return join(dir, `${key}.${requestId}.json`);
+}
+/**
+ * Write every byte, or throw.
+ *
+ * Its own function, and injectable, because the defect it fixes cannot be
+ * reproduced on an ordinary filesystem: `writeSync` returns having written
+ * fewer bytes than it was given without throwing, and the fragment would then
+ * be fsynced and renamed into place as a valid record. A test needs a writer
+ * that behaves that way to hold this closed — without one, deleting the loop
+ * leaves every suite green (raised in review).
+ */
+export function writeAll(fd, bytes, what, write = writeSync) {
+    let written = 0;
+    while (written < bytes.length) {
+        const n = write(fd, bytes, written, bytes.length - written);
+        // Zero means no progress: looping again would spin instead of failing, and
+        // a negative is a contract this cannot interpret. Both refuse.
+        if (n <= 0)
+            throw new Error(`short write to ${what}: ${written}/${bytes.length} bytes`);
+        written += n;
+    }
+}
+/**
+ * Record what this machine's SAS comparison authenticated.
+ *
+ * Written with the same durability as a credential — 0600 in a 0700 directory,
+ * temp file, fsync, rename, fsync the directory — because a half-written
+ * record is one `fetch` would either reject a good bundle over or, worse, read
+ * a truncated digest from.
+ */
+export function recordAuthenticatedDigest(input, env = process.env) {
+    if (!HEX64.test(input.handoffDigest)) {
+        throw new Error('handoff digest must be 64 lowercase hexadecimal characters');
+    }
+    if (!UUID.test(input.requestId)) {
+        throw new Error('request id must be a uuid');
+    }
+    const dir = baseDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // `mkdirSync`'s mode applies only when it CREATES the directory; one that
+    // already exists keeps whatever it had. The comment above claims credential
+    // durability, so the claim is enforced on every write rather than assumed
+    // from the first one — the same reason credentials.ts does it (raised in review).
+    enforceMode(dir, 0o700);
+    const path = pathFor(dir, input.serverOrigin, input.requestId);
+    const record = {
+        requestId: input.requestId,
+        handoffDigest: input.handoffDigest,
+        scopeFingerprint: fingerprintScope(input.secret, input.devicePubkey),
+        recordedAt: new Date().toISOString(),
+    };
+    const tmp = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+    // ONE interval: from the moment this temp exists until the rename returns,
+    // every failure removes it. Not "on a write error" and not "on a rename
+    // error" — those are two of the ways out, and each version of this that
+    // named the operations left another one uncovered. `closeSync` throws too,
+    // and it used to run BEFORE the removal in one branch and outside the
+    // guarded region in the other, so a failure there left the temp behind in
+    // both (raised in review).
+    //
+    // Until the rename returns, this file's existence is known only here, so
+    // nothing else can ever collect it.
+    const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        try {
+            // Written to completion, not "written once". `writeSync` may return
+            // having written FEWER bytes than it was given, without throwing, and
+            // that fragment would then be fsynced and renamed into place as a valid
+            // `.json` — replacing a correct approval with a truncated one and
+            // stopping `fetch` for good. The read side refuses it, which is the
+            // right end state and not a recovery (raised in review).
+            //
+            // Same reasoning as letting `closeSync` throw: a partial success is not
+            // a success, and publishing it is worse than failing here.
+            writeAll(fd, Buffer.from(`${JSON.stringify(record, null, 2)}\n`, 'utf8'), tmp);
+            fsyncSync(fd);
+        }
+        finally {
+            // Deliberately allowed to throw into the catch below: a close that fails
+            // can be reporting a deferred write error, and treating that as success
+            // would publish a record nobody knows is complete.
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+    enforceMode(path, 0o600);
+    const dirFd = openSync(dirname(path), constants.O_RDONLY);
+    try {
+        fsyncSync(dirFd);
+    }
+    finally {
+        closeSync(dirFd);
+    }
+}
+/**
+ * Every settled ceremony recorded for this origin.
+ *
+ * Returns them all rather than choosing. Picking the newest would let a bundle
+ * be checked against a digest from a DIFFERENT ceremony than the one whose
+ * digits a person read aloud, and a check against the wrong value is not a
+ * weaker check — it is no check, wearing the shape of one.
+ */
+export function readAuthenticatedDigests(serverOrigin, 
+// Only the ceremonies THIS credential performed. An origin can hold more
+// than one over its life — a rotation, a second account — and mixing them
+// turns a single clear approval into an ambiguity, or points the comparison
+// at another credential's ceremony.
+secret, devicePubkey, env = process.env) {
+    const mine = fingerprintScope(secret, devicePubkey);
+    const dir = baseDir(env);
+    const prefix = `${Buffer.from(serverOrigin, 'utf8').toString('base64url')}.`;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const found = [];
+    for (const name of names) {
+        if (!name.startsWith(prefix) || !name.endsWith('.json'))
+            continue;
+        const path = join(dir, name);
+        // O_NOFOLLOW: a symlink here would let someone else's file decide which
+        // bundle this machine accepts.
+        const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(fd, 'utf8'));
+        }
+        finally {
+            closeSync(fd);
+        }
+        const r = parsed;
+        // Unreadable is not absent. A record this cannot vouch for must not become
+        // "no record", because "no record" is the branch that refuses every
+        // bundle — turning a corrupted file into a machine that quietly stops
+        // fetching rather than one that says its record is broken.
+        if (typeof r?.['handoffDigest'] !== 'string' ||
+            !HEX64.test(r['handoffDigest']) ||
+            typeof r['requestId'] !== 'string' ||
+            !UUID.test(r['requestId']) ||
+            typeof r['scopeFingerprint'] !== 'string' ||
+            !SCOPE_HEX.test(r['scopeFingerprint'])) {
+            throw new Error(`authenticated digest record is unreadable: ${path}`);
+        }
+        // A different scope's ceremony is not this one's business — skipped, not
+        // an error, because its presence is normal. This only holds because the
+        // value was checked for SHAPE above: without that, a corrupted
+        // fingerprint would be silently filed as "someone else's" and the record
+        // would vanish from view instead of failing, which is the collapse of
+        // unreadable into absent that this file refuses everywhere else.
+        //
+        // What the shape check cannot do: a well-formed value that is simply wrong
+        // is indistinguishable from a genuine other scope. That limit is real and
+        // is not claimed away (raised in review).
+        if (r['scopeFingerprint'] !== mine)
+            continue;
+        found.push({
+            requestId: r['requestId'],
+            handoffDigest: r['handoffDigest'],
+            scopeFingerprint: r['scopeFingerprint'],
+            recordedAt: typeof r['recordedAt'] === 'string' ? r['recordedAt'] : '',
+        });
+    }
+    return found;
+}
+/** Forget one, once its bundle has been taken. */
+export function clearAuthenticatedDigest(serverOrigin, requestId, 
+// Taken but unused for the path, and required anyway: the caller must have
+// the credential whose ceremony this was. A signature that did not ask for
+// it would let one credential's fetch delete another's approval.
+secret, devicePubkey, env = process.env) {
+    const records = readAuthenticatedDigests(serverOrigin, secret, devicePubkey, env);
+    if (!records.some((r) => r.requestId === requestId))
+        return;
+    rmSync(pathFor(baseDir(env), serverOrigin, requestId), { force: true });
+}

package/dist/src/browser.js

@@ -0,0 +1,241 @@
+import { spawn } from 'node:child_process';
+import { platform } from 'node:process';
+// "Press Enter to open it" — deliberately not "open it automatically".
+//
+// The URL and the code stay on screen either way. Opening the page for someone
+// who never saw where it points would take away the one thing that makes a
+// default endpoint safe: the destination is visible before anyone arrives.
+//
+// Two constraints shape everything here:
+//
+//   1. Waiting for Enter must NOT pause the poll. Someone who opens the URL by
+//      hand, or on their phone, gets approved without ever pressing a key, and
+//      the CLI has to notice that. So the keypress is armed alongside the poll,
+//      never awaited by it.
+//   2. Failing to open a browser is NOT a failure to log in. Over ssh, in a
+//      container, on a headless box, there is no browser and there never will
+//      be — exiting there would make those machines unable to log in at all.
+//
+// Raw mode is not used: Enter arrives on its own in line mode, so the terminal's
+// external state is never modified and there is nothing to restore.
+// The URL comes from the SERVER, so it is attacker-controlled whenever the
+// server is. Two independent things keep that from becoming code execution:
+//
+//   1. No shell, on any platform. `cmd /c start` was the original Windows
+//      opener and it is wrong: `shell: false` does not help when the program
+//      being run IS cmd, which re-interprets `&`, `|`, `^` and `%` inside the
+//      argument. `rundll32 url.dll,FileProtocolHandler` takes the URL as a
+//      plain argument, like `open` and `xdg-open` already do.
+//   2. The URL is checked before it is handed to any of them.
+function openerFor(url) {
+    switch (platform) {
+        case 'darwin':
+            return { command: 'open', args: [url] };
+        case 'win32':
+            return { command: 'rundll32', args: ['url.dll,FileProtocolHandler', url] };
+        default:
+            return { command: 'xdg-open', args: [url] };
+    }
+}
+// Two different dangers, two different answers — conflating them is how the
+// wrong control ends up carrying the weight.
+//
+//   INJECTION is closed by never involving a shell. That is `openerFor` above,
+//   and it has nothing to do with which host the URL names.
+//   MISDIRECTION is a host question, and the first answer is that the URL is
+//   always printed, so a person can see where they are being sent.
+//
+// The host pin below is the second answer, and it only applies where we
+// actually know both ends: the official deployment, whose control plane and
+// console are both names we ship. Pinning a self-hosted deployment's console
+// would be guesswork — its layout is not ours to know — so there the printed
+// URL is the whole control.
+export const DEFAULT_ENDPOINT = 'https://api.agmsg.cloud';
+// The ORIGIN, not the host. We know the official console's scheme and port as
+// surely as its name, and a check looser than what we know is a hole the exact
+// width of the difference: `https://app.agmsg.cloud:8443` is a different service
+// on a name the operator would read as correct. The port freedom below belongs
+// to the local/self-hosted branch, where the topology genuinely is not ours.
+const OFFICIAL_CONSOLE_ORIGIN = 'https://app.agmsg.cloud';
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+// `https` everywhere, with plain http allowed only to the loopback interface.
+// That is an exception to a rule, so it is worth saying why it is not a hole:
+// a host an attacker controls cannot be 127.0.0.1, so the case the rule exists
+// to stop cannot reach it.
+function schemeIsAcceptable(target) {
+    if (target.protocol === 'https:')
+        return true;
+    return target.protocol === 'http:' && LOOPBACK.has(target.hostname);
+}
+export function verificationUrlIsSafe(url, endpoint) {
+    let target;
+    let configured;
+    try {
+        target = new URL(url);
+        configured = new URL(endpoint);
+    }
+    catch {
+        return false;
+    }
+    if (!schemeIsAcceptable(target))
+        return false;
+    // Credentials in the authority are never part of a verification URL we would
+    // send someone to, and they make the authority ambiguous to a reader.
+    if (target.username !== '' || target.password !== '')
+        return false;
+    const usingDefault = configured.origin === new URL(DEFAULT_ENDPOINT).origin;
+    if (usingDefault)
+        return target.origin === OFFICIAL_CONSOLE_ORIGIN;
+    // A locally-run stack still gets the loopback check above; beyond that, an
+    // operator who named their own endpoint owns their own topology.
+    return true;
+}
+export function openUrl(url) {
+    const opener = openerFor(url);
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(opener.command, opener.args, {
+                stdio: 'ignore',
+                detached: true,
+            });
+            // An opener that is missing (no xdg-open) emits 'error', not an exit code.
+            child.once('error', () => resolve(false));
+            child.once('spawn', () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+// What "nobody is here" actually means.
+//
+// This used to ask `stdin.isTTY`, and an owner's end-to-end run through an
+// agent printed "Press Enter to open it in your browser" into a stream that
+// was already at EOF: the runner handed the process a terminal and no keys.
+// A terminal is where a keystroke would ARRIVE if one were sent; it is not
+// evidence that anyone can send one. So the question is whether input is
+// still coming, and a closed or finished stream answers no whatever its
+// isTTY says.
+//
+// It stays conservative in the other direction: an open TTY is treated as
+// interactive even though the person may have walked away. Offering a key
+// that nobody presses costs nothing — the poll runs regardless — while
+// withholding it from someone who is there would take away the only
+// convenience this function exists to provide.
+function keypressCanArrive(stdin) {
+    if (!stdin.isTTY)
+        return false;
+    if (stdin.destroyed)
+        return false;
+    if (stdin.readableEnded)
+        return false;
+    // `readable` is false once the stream has ended or been destroyed; an
+    // undefined value (a stream that never set it) is not evidence of either.
+    return stdin.readable !== false;
+}
+// What to say when it cannot. The caller has already printed the URL and the
+// code, so nothing is missing from the screen — what is missing is what the
+// agent reading this should DO, and the failure to say it is what makes an
+// agent answer on the person's behalf.
+const NO_KEYS_GUIDANCE = 'No keypress can reach this command. Show the URL and the code above to the person approving, ' +
+    'and wait: do not open the page for them and do not approve on their behalf. ' +
+    'This command returns on its own once they answer.\n';
+// How long to let the input declare itself finished before offering a key.
+// Measured, not chosen: a pty at EOF answers in single-digit milliseconds
+// locally, and this is two orders above that. It is a delay before a
+// convenience, never before the login itself — the poll is already running
+// and the URL is already on screen.
+const EOF_GRACE_MS = 250;
+// Arms a one-shot Enter -> open. Returns a disarm that is idempotent and must be
+// called on every exit path: a live stdin listener would otherwise hold the
+// process open after login has already finished.
+export function armEnterToOpen(url, endpoint, deps = {}) {
+    const stdin = deps.stdin ?? process.stdin;
+    const write = deps.write ?? ((s) => void process.stdout.write(s));
+    const open = deps.open ?? openUrl;
+    // Refused before anything is offered, not at the moment a key is pressed: a
+    // destination we would not open is not one to advertise either. Login itself
+    // continues — the URL is on screen, and a human who inspects it can still
+    // decide for themselves.
+    if (!verificationUrlIsSafe(url, endpoint)) {
+        // Not an error: login continues and the URL is already on screen. We simply
+        // decline to send someone somewhere we cannot vouch for, and say so.
+        write(`Not offering to open that page — check the URL above before you open it yourself.\n`);
+        return { disarm: () => { } };
+    }
+    // Saying "press Enter" where no keystroke can arrive is an instruction that
+    // can never be followed — so say what CAN be done there instead.
+    if (!keypressCanArrive(stdin)) {
+        write(NO_KEYS_GUIDANCE);
+        return { disarm: () => { } };
+    }
+    // The offer waits for the input to prove itself finished, or not.
+    //
+    // An earlier revision printed it immediately and withdrew it two lines
+    // later when the input turned out to be at EOF. The withdrawal worked and
+    // was still wrong: an owner's run had an agent read the output as it
+    // arrived and report the FIRST line, so the person was told to press a key
+    // that could never be pressed. Order is part of the message when something
+    // else is reading it a line at a time.
+    //
+    // The next revision deferred by one `setImmediate`, which passes against a
+    // fake stream and FAILS on a real one — measured on a pty whose input was
+    // at EOF, the shape the owner actually hit: EOF arrives from a read in a
+    // later poll phase, and the check phase runs before it. There is no
+    // positive signal to wait for instead. A live terminal that nobody is
+    // touching emits nothing at all, so "still open" cannot be observed; only
+    // "finished" can.
+    //
+    // So the wait is for the negative signal, bounded. A finished stream says
+    // so within a read; a live one stays silent and the offer goes out a
+    // fraction of a second later, which costs a person nothing. Anything that
+    // ends after the window is still retracted below — the window narrows the
+    // hole, it does not pretend to close it.
+    let done = false;
+    const disarm = () => {
+        if (done)
+            return;
+        done = true;
+        stdin.off('data', onData);
+        stdin.off('end', onEnd);
+        try {
+            stdin.pause();
+        }
+        catch {
+            // Already closed; there is nothing left to pause.
+        }
+    };
+    const onData = () => {
+        disarm();
+        void open(url).then((ok) => {
+            if (!ok) {
+                write(`Could not open a browser here — open the URL above yourself.\n`);
+            }
+        });
+    };
+    // EOF. If the offer has not gone out yet, it never does — nothing false is
+    // said at all. If a slower runner ends the stream after the offer was made,
+    // the offer is withdrawn, which is the best that can be done once it is on
+    // screen.
+    const onEnd = () => {
+        disarm();
+        write(NO_KEYS_GUIDANCE);
+    };
+    stdin.on('data', onData);
+    stdin.on('end', onEnd);
+    stdin.resume();
+    const pending = deps.defer ?? ((fn) => setTimeout(fn, EOF_GRACE_MS));
+    const timer = pending(() => {
+        if (done)
+            return;
+        write(`Press Enter to open it in your browser (or open the URL yourself).\n`);
+    });
+    timer?.unref?.();
+    // Without this a waiting listener keeps the event loop alive, so the process
+    // would hang after a successful login instead of exiting.
+    stdin.unref?.();
+    return { disarm };
+}

package/dist/src/ceremony.js

@@ -0,0 +1,181 @@
+import { deriveRequestNonce, deriveSas, verifyApproverCommitment, verifySasCommitment, } from '@agmsg-cloud/sas-core';
+// Shared orchestration for the SAS ceremony (spec §3-§4). Both sides run the
+// same waits and the same verification, so there is one place where "is this
+// transcript trustworthy" is decided.
+//
+// THE RULE THIS FILE EXISTS FOR: neither side may take the SAS, or any input to
+// it, from the server. The server returns request_nonce because it is part of
+// the public transcript, and a client that displayed a code derived from it
+// would be asking the server what code to show — which is exactly the check the
+// ceremony is supposed to make impossible to fake. So the value is recomputed
+// here from the two opened nonces every time, and the server's copy is only ever
+// compared against, never used.
+export class CeremonyError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'CeremonyError';
+    }
+}
+// The ceremony only ever moves forwards, so waiting is "has it reached at least
+// here", not "is it exactly here".
+//
+// Waiting for equality is a race the requester loses routinely: the approver
+// opens and then approves, and the row is 'consumed' a few milliseconds later.
+// A requester polling for exactly 'opened' can step straight over that window
+// and report a successful enrollment as a failure. Found by running both sides
+// against one real server — every test that stubbed a side had it exactly-equal
+// and was green.
+const PROGRESSION = ['requester_committed', 'both_committed', 'requester_opened', 'opened', 'consumed'];
+// Ends the ceremony without reaching the end. Not the same as 'consumed', which
+// is the end.
+// 'refused' belongs here even though it costs no attempt: a waiter's question
+// is "can this still finish", and the answer is no. What it costs is a separate
+// question, answered by the ledger and by the server's counters — a waiter that
+// left it out would poll a dead request until it timed out.
+const TERMINAL_FAILURE = ['expired', 'failed', 'refused'];
+function rank(status) {
+    return PROGRESSION.indexOf(status);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll one request until it reaches `want`, or fail.
+ *
+ * A ceremony that reaches a terminal state stops immediately rather than waiting
+ * out the clock: §3.3 makes failure permanent, so continuing to poll would only
+ * delay telling the human that this attempt is over — and §4.1 has already
+ * charged them for it.
+ */
+export async function waitForStatus(client, requestId, want, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5 * 60_000;
+    const pollMs = options.pollMs ?? 1_000;
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const transcript = await client.getEnrollment(requestId);
+        if (TERMINAL_FAILURE.includes(transcript.status)) {
+            throw new CeremonyError('ended', `enrollment ${requestId} is ${transcript.status}`);
+        }
+        const reached = rank(transcript.status);
+        if (reached >= 0 && reached >= rank(want))
+            return transcript;
+        if (now() >= deadline) {
+            throw new CeremonyError('timed_out', `enrollment ${requestId} did not reach ${want} in time`);
+        }
+        await sleep(pollMs);
+    }
+}
+function requireBytes(hex, what) {
+    if (hex === null)
+        throw new CeremonyError('server_transcript_disagrees', `${what} is missing`);
+    return new Uint8Array(Buffer.from(hex, 'hex'));
+}
+/**
+ * Turn a fully opened transcript into the code a human reads aloud.
+ *
+ * Every input is re-derived or re-verified here. `request_nonce` from the server
+ * is checked against the locally computed value and then discarded — if they
+ * disagree, the server is not relaying, and no code should be shown at all.
+ */
+export function sasFromOpenedTranscript(transcript) {
+    if (transcript.status !== 'opened' && transcript.status !== 'consumed') {
+        throw new CeremonyError('server_transcript_disagrees', `transcript is ${transcript.status}`);
+    }
+    const devicePubkey = transcript.device_pubkey;
+    if (devicePubkey === null) {
+        throw new CeremonyError('server_transcript_disagrees', 'device_pubkey is missing');
+    }
+    const openingNonce = requireBytes(transcript.opening_nonce, 'opening_nonce');
+    const approverNonce = requireBytes(transcript.approver_nonce, 'approver_nonce');
+    // The snapshot A committed to. Required, not optional: it is an input to
+    // both the approver commitment and the SAS, so a transcript without it is
+    // one this cannot check or derive from — treating it as absent would mean
+    // showing digits that attest less than the person reading them believes.
+    const handoffDigest = transcript.handoff_digest;
+    if (handoffDigest === null) {
+        throw new CeremonyError('server_transcript_disagrees', 'handoff_digest is missing');
+    }
+    // B's opening must match the commitment fixed before A ever committed.
+    if (!verifySasCommitment(transcript.commitment, devicePubkey, openingNonce)) {
+        throw new CeremonyError('requester_opening_invalid', 'the requester opening does not match its commitment');
+    }
+    // A's opening must match the commitment fixed before B opened.
+    if (transcript.approver_commitment === null) {
+        throw new CeremonyError('server_transcript_disagrees', 'approver_commitment is missing');
+    }
+    if (!verifyApproverCommitment(transcript.approver_commitment, approverNonce, handoffDigest)) {
+        throw new CeremonyError('approver_commitment_invalid', 'the approver opening does not match its commitment');
+    }
+    const requestNonce = deriveRequestNonce(approverNonce, openingNonce);
+    const localHex = Buffer.from(requestNonce).toString('hex');
+    if (transcript.request_nonce !== null && transcript.request_nonce !== localHex) {
+        // Not a mismatch to paper over. The server derived something else from the
+        // same two nonces, which means it is not running the protocol.
+        throw new CeremonyError('server_transcript_disagrees', 'the server request nonce does not match the one derived locally');
+    }
+    return deriveSas(devicePubkey, requestNonce, handoffDigest);
+}
+// How the code is shown. Kept in one place so both terminals render it
+// identically: two machines formatting the same eight digits differently is a
+// comparison the human is more likely to get wrong, and "it looked different on
+// the other screen" is the exact doubt this step must not introduce.
+//
+// The frame is measured from the content rather than written out, because a
+// hand-drawn box drifts the moment the code changes width — and a box that does
+// not line up reads as a rendering bug, which is not what you want the user
+// looking at while deciding whether to trust a key.
+export function renderSasBlock(sas, role) {
+    const other = role === 'requester' ? 'The approving machine' : 'The joining machine';
+    const inner = `   ${sas}   `;
+    const rule = '─'.repeat([...inner].length);
+    return [
+        '',
+        `  ┌${rule}┐`,
+        `  │${inner}│`,
+        `  └${rule}┘`,
+        '',
+        `  ${other} is showing eight digits too. Check they are the same.`,
+        '',
+        // Only the approver is asked anything. Telling the joining machine's
+        // operator to "answer no" pointed at a prompt that does not exist on their
+        // side, one line above the sentence explaining that the approver decides.
+        //
+        // SAID HERE AND NOWHERE ELSE. `request` printed its own version of the
+        // requester's sentence straight after this block, so the screen read: who
+        // decides -> how to compare remotely -> who decides (#195). The block is
+        // the one place that knows which side it is rendering for, so it is the
+        // one place that says it.
+        //
+        // The wording is the LONGER of the two that existed, because it carried
+        // something this one did not: what a `no` means. Deduplicating by keeping
+        // the shorter line would have deleted that with it.
+        ...(role === 'approver'
+            ? ['  If they differ at all, answer no. That is what this check is for.']
+            : [
+                '  The approver decides. If they confirm, this machine is added and can',
+                '  fetch its bundle; if not, nothing is sent and this request is over.',
+            ]),
+        '',
+        // Addressed to the people it applies to, and to nobody else.
+        //
+        // What used to be here was a paragraph for everyone: read the digits
+        // aloud, use a channel where you recognise the voice, do not paste into a
+        // chat, and do not read the code from any window other than this one.
+        //
+        // The ordinary case is one person with two machines in front of them, and
+        // for that person the paragraph was wrong in every line — there is nobody
+        // to read aloud to, no channel, and the last instruction forbids the check
+        // itself: comparing means looking at the other screen. It also introduced
+        // pasting, which is not a thing anyone comparing two screens would have
+        // thought of; naming a wrong way to do this is how it becomes an option.
+        //
+        // And listing prohibitions has a cost beyond the words: whatever the list
+        // leaves out reads as allowed. One sentence saying where the digits must
+        // come from does the work the list was trying to do.
+        '  If you cannot see that screen yourself, have the digits read to you on a',
+        '  call you already trust.',
+        '',
+    ].join('\n');
+}