agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/commands/connect.js

@@ -0,0 +1,273 @@
+import { spawnOssInherit } from '../oss-env.js';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { CourierClient, CourierError } from '../api.js';
+import { originOf, readCredential } from '../credentials.js';
+import { generateDeviceIdentity, publicKeyOf, remoteTeamId } from '../oss.js';
+import { deviceIdentityPath } from '../paths.js';
+import { NEEDS, ensurePreflight, formatPreflight, preflight } from '../preflight.js';
+import { shellArg } from '../shell-arg.js';
+function runInherit(command, args) {
+    return new Promise((resolve, reject) => {
+        // stdio inherited: `remote.sh connect` prints its own progress, and
+        // swallowing it would leave the operator watching nothing during the
+        // slowest step. It may also prompt.
+        const child = spawnOssInherit(command, args);
+        child.on('error', reject);
+        child.on('close', (code) => resolve(code ?? 1));
+    });
+}
+export async function cmdConnect(config, opts) {
+    // Checked BEFORE anything is sent. A missing prerequisite discovered midway
+    // costs the operator an approval they cannot get back.
+    ensurePreflight(preflight(config.scriptsDir, NEEDS.connect));
+    // The capability URL, not the control-plane endpoint. They are different
+    // hosts in production — the control plane mints the URL, the sync gateway
+    // answers it — and sending a team to the wrong one is not a redirect, it is
+    // a request the gateway never sees.
+    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`);
+    }
+    process.stdout.write(`\nConnecting "${opts.team}" as machine "${credential.machineName}".\n`);
+    const run = opts.runner ?? runInherit;
+    const code = await run('bash', [
+        join(config.scriptsDir, 'remote.sh'),
+        'connect',
+        '--endpoint',
+        credential.capabilityUrl,
+        '--e2ee',
+        opts.team,
+    ]);
+    if (code !== 0) {
+        // A non-zero exit used to end the command here, and that is the whole of
+        // issue #146: the OSS step registers the team upstream and THEN something
+        // fails — a 502 from the gateway is enough — so this returns before the
+        // machine is registered. Running connect again cannot repair it, because
+        // the OSS step now refuses with a uniqueness conflict ("a team_id registers
+        // once ... not a transient error to retry") and exits non-zero again. The
+        // one place that can register this machine sits behind a gate that a retry
+        // can never pass, and the team becomes one nobody else can ever join.
+        //
+        // Nothing needs to be rolled back and no delete endpoint is needed. The
+        // server holds no half-finished state: the team's claim row is written by
+        // the edge guard when the OSS step syncs, which is exactly the state it
+        // should be in. What is missing is the device registration, and everything
+        // it needs — the team's remote id, this machine's key, its name — is a fact
+        // this machine already has or can recompute.
+        //
+        // So a failed OSS step is not a reason to skip the registration. It is a
+        // reason to ask whether the registration is still wanted, and the OSS
+        // side's own status answers that: an active binding means the team IS
+        // registered upstream, whatever this exit code says.
+        let bound = false;
+        try {
+            await (opts.teamIdOf ?? remoteTeamId)(config.scriptsDir, opts.team);
+            bound = true;
+        }
+        catch {
+            // Not bound: the OSS step failed before it registered anything, so there
+            // is nothing for this machine to be the first device OF.
+        }
+        if (!bound) {
+            // The OSS script has already said what went wrong on this terminal;
+            // repeating a guess on top of it would compete with the real message.
+            throw new Error(`connect failed (remote.sh exited ${code})`);
+        }
+        // States only what has happened. The registration below re-reads the
+        // team's status, generates or reads a device key, and calls the server —
+        // any of which can fail, and a control plane that is down fails all three.
+        // An earlier version of this line said the run "finishes registering this
+        // machine" and that "there is nothing else to do", printed here, before any
+        // of it had been attempted: on a failure the terminal would have claimed a
+        // completed act while has_device stayed false — the exact state this whole
+        // change is about. Success is claimed once, after the call returns.
+        process.stdout.write(`\nThe step above failed (remote.sh exited ${code}), but "${opts.team}" is registered\n` +
+            'on the remote, so this run now tries to register this machine.\n');
+    }
+    // Register this machine as the team's first device.
+    //
+    // Approving anyone requires the approver to BE a registered device, and the
+    // only caller the server accepts for the bootstrap is the capability that
+    // claimed the team. This is the one place where that is guaranteed to be
+    // true, which is why it lives here rather than in a command of its own: a
+    // separate command could be run later, from a machine whose capability never
+    // claimed anything, and there would be no way to tell.
+    //
+    // Without this the first machine can never approve a second one, so a team
+    // that connects successfully is still a team nobody else can ever join.
+    await registerThisMachine(config, opts, credential.machineName);
+    // Reached on both paths, and it is the same sentence on purpose: what it
+    // claims — this machine can approve others — is true either way, and it is
+    // the claim the failure above used to make false.
+    //
+    // AFTER the call, and only after it. This is the one place either path says
+    // the registration happened.
+    process.stdout.write(`"${opts.team}" is on the hosted service, and this machine can approve others.\n`);
+    // The routes the OSS scripts stopped naming once this CLI took the job
+    // (AGMSG_OPERATOR_GUIDANCE=caller). Taking it on is an obligation: those
+    // scripts no longer say what to do next, so if this said nothing, nobody
+    // would.
+    //
+    // It says what to DO and why, and asserts nothing about what is already
+    // true. The first version of this said "this machine now holds the only
+    // copy", which is false on a re-connect: `bootstrapDevice` is idempotent, so
+    // a team that already has a recovery vault and a second machine reaches this
+    // line too (raised in review).
+    //
+    // And it cannot be fixed by looking: the vault is per ACCOUNT, so its
+    // existence does not say whether THIS team is in it, and finding out means
+    // opening it — which needs the recovery key nobody has typed here. A
+    // sentence about where the only copy is would be a guess whichever way it
+    // went. The condition is named instead, and it is true in every case.
+    process.stdout.write(`\nBack these keys up: \`agmsg-cloud recovery setup ${shellArg(opts.team)}\`.\n` +
+        'Until a team is in your recovery vault, the only copies of its keys are on\n' +
+        'the machines that hold them; once it is there, the recovery key opens it again.\n' +
+        `\nTo add a second machine, run \`agmsg-cloud sync ${shellArg(opts.team)}\` there and answer here.\n` +
+        // The subject is the operator, and it has to be. Something IS carried
+        // between the machines after the yes — the sealed bundle, which is what
+        // this feature is for. What nobody carries is a value, by hand, from one
+        // screen to the other, and that is the property the ceremony buys
+        // (raised in review).
+        'You do not carry any value between the machines yourself: both screens show\n' +
+        'eight digits and you check they are the same.\n');
+    if (code !== 0) {
+        // Now that it is true, the operator can be told the failure needs nothing
+        // further — but only about the case where that is so. The error itself is
+        // still theirs to read; this does not summarise it.
+        process.stdout.write('Read the error above: if it was a uniqueness conflict, the team was already connected\n' +
+            'and there is nothing else to do.\n');
+    }
+}
+async function registerThisMachine(config, opts, machineName) {
+    // The team's server-side id comes from the OSS side's own status output —
+    // the local name and the remote id are unrelated namespaces, and `connect`
+    // is the only thing that ever links them.
+    const teamId = await (opts.teamIdOf ?? remoteTeamId)(config.scriptsDir, opts.team);
+    // The device key lives under AGMSG_CLOUD_HOME, like every other per-machine
+    // secret, so a second machine driven from the same host with its own HOME
+    // gets its own identity rather than sharing this one.
+    const idPath = deviceIdentityPath();
+    mkdirSync(dirname(idPath), { recursive: true, mode: 0o700 });
+    const pubkey = existsSync(idPath) ? await publicKeyOf(idPath) : await generateDeviceIdentity(idPath);
+    const client = new CourierClient(config);
+    try {
+        await client.bootstrapDevice({
+            team_id: teamId,
+            device_pubkey: pubkey,
+            label: machineName,
+        });
+    }
+    catch (err) {
+        // The server distinguishes these because a client cannot: the device list
+        // is the org's recipient set and carries no capability, so seeing this key
+        // in it proves nothing about who registered it.
+        if (err instanceof CourierError && err.code === 'device_key_mismatch') {
+            throw new Error(`this machine is already registered under a different device key than the one in ${deviceIdentityPath()}.\n\n` +
+                'That happens when the key file is replaced or restored from elsewhere. Messages sent to this\n' +
+                'machine are addressed to the registered key, so it cannot read them with the key it has.\n' +
+                'Ask an approver to remove this machine, then run connect again to register the current key.');
+        }
+        if (err instanceof CourierError && err.code === 'device_key_in_use') {
+            throw new Error(`the device key in ${deviceIdentityPath()} is already registered by another machine.\n\n` +
+                'Each machine needs its own key; this one looks copied from somewhere else. Move that file\n' +
+                'aside and run connect again to generate a fresh identity for this machine.');
+        }
+        // Written out because this change routes more traffic here: a connect whose
+        // OSS step failed now reaches the registration instead of stopping before
+        // it, so a bare `courier request failed: 403 forbidden` would become the
+        // thing a person sees while recovering.
+        //
+        // What a 403 here means, measured rather than guessed. The route's
+        // `requireCapability` already refuses a capability that is revoked or not
+        // yet activated with a 401, so by the time the handler runs the caller IS
+        // live and the only refusal left is `not_claimant`. (`capability_not_live`
+        // survives inside the transaction for the race where it dies mid-command —
+        // and that lands in the same place, because a replacement credential is a
+        // new capability and therefore not the claimant either.)
+        //
+        // RE-RUNNING CONNECT IS NOT AN EXIT, and an earlier version of this message
+        // offered it. `claimOrVerifyTeam` records the claiming capability with
+        // ON CONFLICT DO NOTHING and nothing anywhere reassigns it, so a capability
+        // that is not the claimant never becomes one. Connect from here returns to
+        // this same 403 forever.
+        if (err instanceof CourierError && err.status === 403) {
+            throw new Error(await forbiddenAdvice(client, opts.team, pubkey));
+        }
+        throw err;
+    }
+}
+/**
+ * What to tell someone the server refused to register.
+ *
+ * The exit is the approved enrollment path — `sync` — and whether that path is
+ * open depends on a fact this command can look up rather than assume: does the
+ * account have a machine that could approve? Enrollment needs an approver, and
+ * an approver is a registered device.
+ *
+ * The case with no approver is a real one and it has no way out today. That is
+ * written plainly instead of offering a command that will wait forever, because
+ * a person who is told there is no recovery stops spending time looking for one.
+ *
+ * WHY NOT BUILD A WAY BACK. Reassigning a team's claim to a live capability
+ * would fix it, and it is a change nobody should make inside a bug fix: it
+ * decides who may take over a team whose first machine is gone, and the obvious
+ * answer — any live capability in the org — turns a revoked machine into "any
+ * machine may become device-0 for that team", which is part of what revoking
+ * was for. Named here so the next person who finds this message unhelpful
+ * reaches the same question rather than the same guess.
+ */
+async function forbiddenAdvice(client, team, ownPubkey) {
+    const head = `the server would not register this machine for '${team}'.\n\n` +
+        'It is not the machine that first connected this team, and only that one can register\n' +
+        'without an approver. That is recorded once and never moves, so running connect again\n' +
+        'from here will always end exactly here.\n\n';
+    // OTHER machines, not machines. The list is the org's recipient set and
+    // includes this capability's own device — and approveEnrollment refuses an
+    // approver whose capability is the requester's, so a machine cannot approve
+    // its own request. Counting the list would offer `sync` to an account whose
+    // only device is this one, which is the same dead end as the empty case
+    // wearing a different number (raised in review).
+    //
+    // Matched on the device key rather than a capability id, because the list
+    // deliberately carries no capability: it is the recipient set, and the server
+    // keeps it that way so a key appearing in it proves nothing about who
+    // registered it.
+    let approvers = null;
+    try {
+        const devices = await client.listDevices();
+        approvers = devices.filter((d) => d.devicePubkey !== ownPubkey).length;
+    }
+    catch {
+        // Could not ask — most likely this machine's credential just stopped being
+        // live. Said as the uncertainty it is.
+        approvers = null;
+    }
+    if (approvers === null) {
+        return (head +
+            'This machine could not read the account\'s machine list, so its credential may have\n' +
+            'expired mid-command. Sign in again, then join the team from here:\n' +
+            '    agmsg-cloud login\n' +
+            `    agmsg-cloud sync ${shellArg(team)}`);
+    }
+    if (approvers === 0) {
+        return (head +
+            'There is also no OTHER machine on this account that could approve a request — and a\n' +
+            'machine cannot approve its own — so joining is not open either. THERE IS NO WAY TO\n' +
+            'RECOVER THIS TEAM FROM THIS ACCOUNT TODAY: the machine that claimed it can no longer\n' +
+            'register, and enrollment needs an approver that does not exist. Reported rather than\n' +
+            'dressed up as a command, so you do not spend the evening on one that cannot work.');
+    }
+    return (head +
+        'Join it from here instead — this account has another machine that can approve the\n' +
+        'request (a machine cannot approve its own):\n' +
+        `    agmsg-cloud sync ${shellArg(team)}`);
+}
+// Takes a scripts directory, not a CliConfig: this runs before a credential
+// exists, which is the point of a dry run.
+export function cmdConnectPreflight(scriptsDir) {
+    const checks = preflight(scriptsDir, NEEDS.connect);
+    process.stdout.write(`\nChecking what connect needs:\n\n${formatPreflight(checks)}`);
+    if (!checks.ok)
+        throw new Error('prerequisites are missing');
+}

package/dist/src/commands/fetch.js

@@ -0,0 +1,249 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CourierClient } from '../api.js';
+import { clearAuthenticatedDigest, readAuthenticatedDigests } from '../authenticated-digest.js';
+import { originOf } from '../credentials.js';
+import { decryptWithIdentity, localTeamLookup, publicKeyOf, unlockBundle, verifyHandoffDigest, } from '../oss.js';
+import { deviceIdentityPath } from '../paths.js';
+import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
+// (c, part 2) B fetches the sealed bundles addressed to its device, opens each
+// with its device identity, and feeds the recovered handoff bundle to
+// `remote.sh unlock --bundle` for the given team, then acks it (server deletes).
+export async function cmdFetch(config, args, 
+// Injected by the tests, so a run can be pointed at its own cloud home
+// without touching the operator's.
+env = process.env) {
+    // This ends in `remote.sh unlock`, so a machine without the scripts fails at
+    // the last step — after the bundle has been fetched and decrypted. Checked
+    // first, the same way connect checks.
+    ensurePreflight(preflight(config.scriptsDir, NEEDS.fetch));
+    const idPath = deviceIdentityPath();
+    // The device key this machine will decrypt with. Part of the scope an
+    // approval was recorded under, so a regenerated identity does not inherit
+    // the previous one's ceremonies (raised in review).
+    const devicePubkey = await publicKeyOf(idPath);
+    // ASKED BEFORE THE QUEUE IS REPORTED ON (#145).
+    //
+    // `fetchBlobs` is scoped to the DEVICE, not to the team, and the team name is
+    // not read until `unlock` at the far end — so an empty queue and a mistyped
+    // name produced the same sentence. Measured on one machine with one
+    // credential:
+    //
+    //   fetch walkfresh1        -> no pending bundles   (real team, empty queue)
+    //   fetch zzz-no-such-team  -> no pending bundles   (never existed)
+    //
+    // "no pending bundles" was true of the second and useless: someone waits for
+    // a bundle that will never arrive under that name. It is the same argument
+    // the `--confirm-digest` branch below already makes out loud — a thing
+    // silently ignored is how someone keeps believing they are the check.
+    //
+    // The queue is unchanged and so is every gate after it. What changes is that
+    // a name this machine does not have is refused BY NAME instead of answered.
+    // STOPS AT WHAT WAS OBSERVED, which is that the lookup did not succeed.
+    //
+    // It said "this machine has no team called X" — an assertion about absence,
+    // from a non-zero exit that has more than one cause: an unknown name, a
+    // config that could not be read, a store lock, the script failing to start.
+    // This repository has already MEASURED that the first two are
+    // indistinguishable from here — a corrupt team and an unconnected one give
+    // the same exit code and the same sentence (agmsg#650, found while reviewing
+    // #192). Naming a cause that was ruled indistinguishable, and then printing
+    // the store's own words underneath, does not undo the first line: the first
+    // line is what gets believed.
+    //
+    // So the two readings are given, and the store's words carry whichever it is
+    // (raised in review).
+    const lookup = await localTeamLookup(config.scriptsDir, args.team);
+    if (!lookup.known) {
+        throw new Error(`this machine could not confirm a team called ${JSON.stringify(args.team)}, so there is\n` +
+            '  nothing here it can unlock.\n' +
+            (lookup.said ? `\n  The store said: ${lookup.said}\n` : '') +
+            '\n  That reads two ways and this machine cannot tell them apart: there may be no\n' +
+            '  team by that name here, or its state could not be read.\n' +
+            '\n  If the name is right, `agmsg-cloud pull` is what puts a team on a machine, and\n' +
+            '  `agmsg-cloud sync` does that and this in one go.');
+    }
+    const client = new CourierClient(config);
+    const blobs = await client.fetchBlobs();
+    if (blobs.length === 0) {
+        // Now this says something: the team IS here, and nothing is waiting.
+        process.stdout.write('no pending bundles\n');
+        return;
+    }
+    // The authenticated digest IDENTIFIES the bundle, it does not merely check
+    // it. An earlier version refused outright whenever more than one was queued,
+    // which was a dead end rather than a gate: the same queue returns the same
+    // blobs next time, so two honest approvals could wedge a device forever
+    // while the error told the operator to do something no command could do.
+    //
+    // So every queued blob is opened in scratch and asked for its digest, and the
+    // one matching what this machine's ceremony authenticated is the one that
+    // runs. The rest are left untouched — still queued, still fetchable once
+    // their own approval is the recorded one.
+    const scratch = mkdtempSync(join(tmpdir(), 'agmsg-cloud-'));
+    try {
+        // What the ceremony authenticated on this machine — the digest the SAS was
+        // derived over, saved by `request` when the codes matched. Nobody reads it
+        // aloud; that step existed only because this comparison did not.
+        //
+        // This is the value the bundle is checked against. It used to be a 64-hex
+        // string the operator typed, connected to the ceremony only by someone
+        // reading it correctly; binding the digest into the SAS moved that check
+        // from the person to the machine, and this is where it lands (spec
+        // 3.2.1).
+        const authenticated = readAuthenticatedDigests(originOf(config.baseUrl), config.secret, devicePubkey, env);
+        if (authenticated.length === 0) {
+            // Refused. "No record" is not "the machine checked and agreed", and
+            // treating it as such would leave every machine one missing file away
+            // from accepting a bundle nothing vouched for.
+            throw new Error('this machine has no digest from an approved enrollment.\n\n' +
+                'A bundle is only accepted when it matches the snapshot the eight-digit\n' +
+                'code authenticated, and no such approval is recorded here. Run\n' +
+                '`agmsg-cloud request <label>` and have it approved again.');
+        }
+        if (authenticated.length > 1) {
+            // Never a silent choice. Checking against the wrong ceremony's digest is
+            // not a weaker check — it is no check, in the shape of one.
+            const ids = authenticated.map((a) => `  ${a.requestId}  (${a.recordedAt})`).join('\n');
+            throw new Error(`${authenticated.length} approved enrollments are recorded for this service:\n\n${ids}\n\n` +
+                'Which one this bundle belongs to cannot be decided from here.');
+        }
+        const consumed = authenticated[0];
+        const expected = consumed.handoffDigest;
+        const matches = [];
+        // Two different things, and collapsing them is the defect this splits.
+        //
+        //   unreadable   the blob itself did not open. That IS a fact about the
+        //                blob: it is not addressed to this key, or it is damaged.
+        //   unchecked    the comparison never ran. That is a fact about this
+        //                machine — a shell-out that failed, a registry lock held
+        //                by another process — and says NOTHING about the bundle.
+        //
+        // Counted apart because the sentence at the end differs. "Check the digest
+        // with the approver" is a claim that a comparison happened and disagreed.
+        // Said after a lock timeout, it sends the operator to their approver over
+        // an infrastructure failure, wearing the face of the one security check
+        // this ceremony exists to perform.
+        let unreadable = 0;
+        let comparedAndDiffered = 0;
+        const unchecked = [];
+        for (const [i, blob] of blobs.entries()) {
+            // A fixed local name from the loop index, never the server-supplied id: a
+            // compromised server could otherwise return '../../x' and steer the
+            // decrypted secret bundle outside scratch.
+            const bundleFile = join(scratch, `bundle-${i}.bundle`);
+            let digest;
+            try {
+                const bundle = await decryptWithIdentity(idPath, Buffer.from(blob.ciphertext, 'base64'));
+                writeFileSync(bundleFile, bundle, { mode: 0o600 });
+                try {
+                    digest = await verifyHandoffDigest(config.scriptsDir, args.team, bundleFile, join(scratch, `verify-${i}`));
+                }
+                catch (err) {
+                    // The verifier shells out, so this catches a bundle it refused AND a
+                    // run that never happened — a lock it could not take, a missing
+                    // script, a killed process. Those cannot be told apart from here:
+                    // the exit code is non-zero for both.
+                    //
+                    // So it is recorded as NO USABLE RESULT — not as "the run did not
+                    // happen", which is one of the two and cannot be told from the other.
+                    // What is known is only that no comparison this machine can stand
+                    // behind came out of it; whether the bundle matches is undetermined.
+                    unchecked.push(err instanceof Error ? err.message : String(err));
+                    continue;
+                }
+            }
+            catch {
+                // One unopenable blob must not hide a good one behind it — that would
+                // be the same dead end in a different shape. It is counted and
+                // reported, never silently dropped.
+                unreadable += 1;
+                continue;
+            }
+            // The recorded value is the only one there is now. It came from the
+            // transcript the SAS was derived over, so this comparison is the one the
+            // eight digits stood for.
+            if (digest === expected)
+                matches.push({ blob, file: bundleFile });
+            else
+                comparedAndDiffered += 1;
+        }
+        if (matches.length === 0) {
+            // "None matched" is only a MISMATCH when every bundle was compared.
+            //
+            // A blob that did not open was never digest-checked, and a verifier that
+            // returned nothing usable produced no comparison either. If the bundle
+            // the approver sealed is among those, then nothing here disagrees with
+            // the eight digits — the evidence is simply missing. Saying "check with
+            // the approver" in that state sends someone to re-read a code over a
+            // comparison that never reached their bundle (raised in review).
+            if (unreadable > 0 || unchecked.length > 0) {
+                const parts = [];
+                if (comparedAndDiffered > 0) {
+                    parts.push(`  ${comparedAndDiffered} were compared and did not match`);
+                }
+                if (unreadable > 0) {
+                    parts.push(`  ${unreadable} could not be opened on this machine`);
+                }
+                if (unchecked.length > 0) {
+                    parts.push(`  ${unchecked.length} produced no usable result from the check\n` +
+                        `      the first reason was: ${unchecked[0]}`);
+                }
+                throw new Error(`could not establish whether any of the ${blobs.length} queued bundle(s) is the one ` +
+                    `you approved.\n\n${parts.join('\n')}\n\n` +
+                    'A bundle that was not compared may be the one you approved, so this is NOT\n' +
+                    'established as a digest mismatch. Fix the reasons above and run this again\n' +
+                    'before asking the approver to re-read the code.');
+            }
+            throw new Error(`none of the ${blobs.length} queued bundle(s) has the digest you were given. ` +
+                `All ${blobs.length} were opened and compared, and none matched. Check the digest\n` +
+                'with the approver — this is the mismatch the confirmation exists to catch.');
+        }
+        // A match is positive evidence about THAT bundle: its digest equals the one
+        // the eight digits stood for. A bundle whose check never ran is an absence
+        // of evidence about a different bundle, and absence of evidence about one
+        // does not weaken the proof about another — so this proceeds. It says so,
+        // because bundles left queued are otherwise a silent oddity.
+        if (unchecked.length > 0) {
+            process.stdout.write(`note: ${unchecked.length} other queued bundle(s) could not be verified on this machine ` +
+                `(${unchecked[0]}). The one taken below WAS checked against your digest, so this is ` +
+                'not a mismatch; the others stay queued.\n');
+        }
+        // Several matches is NOT a refusal. The digest binds the latest canonical
+        // snapshot that `unlock` will adopt — not the courier blob that carried it —
+        // and nothing anywhere distinguishes one blob from another: the ceremony
+        // authenticates a snapshot, not a delivery. Bundles that completed
+        // verification under the same digest are
+        // therefore equivalent in exactly what this ceremony confirms, so one is
+        // taken and the rest are left queued. Refusing here would have been a
+        // permanent stop that no new digest could clear.
+        //
+        // The choice is made from the VERIFIED matching set, never from the raw
+        // queue: picking an unverified blob by position would not be identification.
+        const { blob, file } = matches[0];
+        await unlockBundle(config.scriptsDir, args.team, file, expected);
+        await client.ackBlob(blob.id);
+        // Consumed only now, and the order is load-bearing.
+        //
+        // Clearing before the ack would throw away the expected digest while the
+        // blob is still queued, so the retry after a failed ack would arrive with
+        // nothing to compare against — and with no record, `fetch` refuses. The
+        // bundle is sitting there, correct and approved, and this machine can no
+        // longer take it. That is the failure, not a weaker check.
+        //
+        // Kept until the ceremony is finished on the server, then removed, because
+        // a record that outlives its enrollment turns every later fetch into "two
+        // approvals are recorded" and refuses just as permanently (raised in review).
+        clearAuthenticatedDigest(originOf(config.baseUrl), consumed.requestId, config.secret, devicePubkey, env);
+        const others = blobs.length - 1;
+        const duplicates = matches.length - 1;
+        process.stdout.write(`unlocked and acked the confirmed bundle` +
+            (others > 0 ? `; ${others} other bundle(s) left queued` : '') +
+            (duplicates > 0 ? ` (${duplicates} of them carry the same digest)` : '') +
+            '\n');
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}