insta 0.0.72 → 0.0.74

package/dist/commands/compute.js

@@ -1,6 +1,6 @@
 import { ApiClient, ApiError, requireProject } from '../api.js';
-import { info, printJson, handleApproval, relayExitCode } from '../util.js';
-import { resolveComputeServiceId, q, parseVolumeGib } from './services.js';
+import { info, printJson, handleApproval, relayExitCode, writeFileAtomicSync, resolveThroughSymlink } from '../util.js';
+import { resolveComputeServiceId, resolveSoleService, q, parseVolumeGib } from './services.js';
 export const isWorker = (s) => s.port === 0;
 // One line per compute service for the disambiguation error: name, region, default URL, status —
 // enough to pick one without a second command. Pure, exported for tests.
@@ -740,4 +740,1134 @@ export async function computeLimits(serviceName, opts) {
     const l = res.body.limits;
     info(`compute ${res.body.service?.name ?? id}: ceiling set to ${l.cpu} vCPU / ${fmtMb(l.memoryMb)}`);
 }
+// ---- ssh (interactive sessions) --------------------------------------------
+import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { aliasFor, certifiesPublicKey, hasOwnedBlock, isSafeAlias, isSafeConfigValue, isSafeSSHHost, isSafeSSHUsername, isSafeTimestamp, isSSHCertificateRecord, mayWidenCAHost, parseCAPublicKey, planCertAuthority, renderConfigBlock, revertCertAuthority, upsertConfigBlock, } from './ssh-config.js';
+/** Where this CLI keeps its own SSH material. Deliberately NOT ~/.ssh: we never
+ *  touch a key the user already had, and a dedicated key pairs with
+ *  IdentitiesOnly to avoid being identified by the wrong one. */
+export const instaSSHDir = () => join(homedir(), '.insta', 'ssh');
+export const instaKeyPath = () => join(instaSSHDir(), 'id_ed25519');
+/** One certificate file per alias. A certificate is issued for ONE service, so
+ *  a single shared file cannot serve a project with two compute services. */
+export const instaCertPath = (alias) => join(instaSSHDir(), `${alias}-cert.pub`);
+export const instaAliasStorePath = () => join(instaSSHDir(), 'aliases.json');
+/** The known_hosts file the trust anchor goes into, and the one every stanza we
+ *  own pins with UserKnownHostsFile.
+ *
+ *  ONE definition on purpose. The anchor is only worth anything if the config
+ *  sends ssh to the file it was written to, so "where the anchor lives" and
+ *  "where the alias looks" must not be two expressions that can drift apart. */
+export const userKnownHostsPath = () => join(homedir(), '.ssh', 'known_hosts');
+/** The renewal-hook command prefix. ssh-config.ts appends the validated alias. */
+export const ENSURE_CERT_COMMAND = 'insta __ssh-ensure-cert';
+/** Never throws: a missing or hand-mangled store must degrade to "nothing is
+ *  set up", not break `ssh` for every alias. */
+export function readAliasStore(path = instaAliasStorePath()) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        // Each RECORD is validated, not just the outer object. A cast here let a
+        // single hand-edited entry through to hostEntries, where a missing host
+        // rendered `HostName undefined` -- and one bad stanza is enough for
+        // OpenSSH to reject the whole file, so every OTHER alias stopped working
+        // too. Dropping the bad entry keeps the blast radius at the entry.
+        const out = {};
+        for (const [alias, r] of Object.entries(parsed)) {
+            if (isValidAliasRecord(r))
+                out[alias] = r;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Whether a stored record can still describe a working alias. */
+export function isValidAliasRecord(r) {
+    if (!r || typeof r !== 'object' || Array.isArray(r))
+        return false;
+    const v = r;
+    return typeof v.projectId === 'string' && v.projectId !== ''
+        && typeof v.serviceId === 'string' && v.serviceId !== ''
+        && (v.branch === undefined || typeof v.branch === 'string')
+        && isSafeConfigValue(v.host) && isSafeConfigValue(v.username);
+}
+/** Refuse to point an existing alias at a different service.
+ *
+ *  An alias is derived from the SERVICE NAME alone, which is unique only within
+ *  a branch. Two projects that each call a service `api` -- the ordinary case,
+ *  not a contrived one -- would otherwise have the second setup silently
+ *  repoint `api.insta` at the first one's host, and the developer would land a
+ *  shell in the WRONG PROJECT while every visible signal said the command
+ *  worked. Refused by name rather than auto-renamed: picking which `api` they
+ *  meant is the same guess one level up.
+ */
+export function assertAliasFree(store, alias, want) {
+    const held = store[alias];
+    if (!held)
+        return;
+    const same = held.projectId === want.projectId
+        && held.serviceId === want.serviceId
+        && (held.branch ?? '') === (want.branch ?? '');
+    if (same)
+        return;
+    throw new Error(`the alias ${alias} is already set up for a different service ` +
+        `(project ${held.projectId}, service ${held.serviceId}${held.branch ? `, branch ${held.branch}` : ''}).\n` +
+        `Rename one of the services, or remove "${alias}" from ${instaAliasStorePath()} and run --setup again.`);
+}
+export function writeAliasStore(store, path = instaAliasStorePath()) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileAtomicSync(path, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 });
+}
+/** The ssh_config entries for everything set up so far. Rendered from the whole
+ *  store, not just the service being set up: our block is replaced wholesale,
+ *  so rendering one entry would delete the stanzas of every other service. */
+export function hostEntries(store) {
+    return Object.entries(store)
+        // Both halves, and the second is not redundant with readAliasStore: this
+        // function is also called with a store held in memory, so the check has to
+        // sit where the rendering does.
+        .filter(([alias, r]) => isSafeAlias(alias) && isValidAliasRecord(r))
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([alias, r]) => ({ alias, hostName: r.host, user: r.username, certificateFile: instaCertPath(alias) }));
+}
+/**
+ * When `ssh-keygen -L` output says the certificate stops being valid, or
+ * `undefined` when that cannot be established.
+ *
+ * `undefined` is not "valid forever". Both the no-match case and a date the
+ * platform formats differently have to read as "cannot confirm", because a
+ * NaN comparison is false and would otherwise pass for healthy.
+ */
+export function parseCertValidUntil(keygenOutput) {
+    const m = /Valid:.*to (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})/.exec(keygenOutput);
+    if (!m || !m[1])
+        return undefined;
+    const until = new Date(m[1]).getTime();
+    return Number.isNaN(until) ? undefined : until;
+}
+const sshKeygenReadCert = (certPath) => execFileSync('ssh-keygen', ['-L', '-f', certPath], { encoding: 'utf8' });
+/**
+ * Whether the certificate at `certPath` should be re-issued.
+ *
+ * Every uncertain case renews. "Cannot confirm it is valid" and "it is valid"
+ * must not collapse into the same answer: an unnecessary renewal costs one
+ * HTTPS call, and the opposite costs a login that fails with no explanation.
+ */
+export function certNeedsRenewal(certPath, { now = Date.now(), marginMs = 5 * 60_000, read = sshKeygenReadCert } = {}) {
+    if (!existsSync(certPath))
+        return true;
+    try {
+        const until = parseCertValidUntil(read(certPath));
+        if (until === undefined)
+            return true;
+        return until - marginMs <= now;
+    }
+    catch {
+        return true;
+    }
+}
+/** The public key of the pair every certificate is issued for, DERIVED from
+ *  the private key -- the one file that decides whether a certificate can be
+ *  used at all.
+ *
+ *  `id_ed25519.pub` is a convenience copy, and trusting it was a hole. A copy
+ *  that had been replaced or corrupted was what got sent to the platform; the
+ *  certificate came back for THAT key; certifiesPublicKey compared it against
+ *  the same copy and agreed; and the working certificate was replaced by one
+ *  the private key cannot use. `ssh-keygen -y` reads the private key and
+ *  prints its public half, so what is sent, checked and recorded is the key
+ *  ssh will actually offer. A copy that disagrees is rewritten from it, and a
+ *  missing one -- a first generation interrupted between its two writes -- is
+ *  recreated rather than failing every setup thereafter. A private key
+ *  ssh-keygen cannot read fails HERE, before anything is minted or replaced,
+ *  and says what to do.
+ *
+ *  Generation is SERIALISED on the setup lock. Two first-ever setups on a
+ *  fresh machine -- a script setting up `api` and `worker` side by side is the
+ *  ordinary way to get there -- both found no key and both ran ssh-keygen at
+ *  the same path; the second hit "already exists, overwrite?" on a closed
+ *  stdin and failed. It is the same lock the setup transaction takes, which is
+ *  safe only because every caller runs this BEFORE taking that lock itself:
+ *  the lock is not re-entrant. A key already on disk takes no lock. */
+function ensureKeyPair() {
+    const key = instaKeyPath();
+    if (!existsSync(key)) {
+        withAliasStoreLock(() => {
+            mkdirSync(instaSSHDir(), { recursive: true, mode: 0o700 });
+            // Re-checked under the lock: the process this one queued behind may have
+            // been the one generating it.
+            if (!existsSync(key)) {
+                execFileSync('ssh-keygen', ['-t', 'ed25519', '-N', '', '-C', 'insta compute ssh', '-f', key], { stdio: 'pipe' });
+            }
+        });
+    }
+    chmodSync(key, 0o600);
+    let derived;
+    try {
+        derived = execFileSync('ssh-keygen', ['-y', '-f', key], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === 'ENOENT')
+            throw new Error('ssh-keygen is not installed, so the ssh key cannot be read -- install OpenSSH and run again');
+        const why = String(err.stderr ?? '').trim().split('\n')[0] || err.message;
+        throw new Error(`the ssh key at ${key} cannot be read by ssh-keygen (${why}); move it aside and run --setup again to generate a new one`);
+    }
+    const pub = key + '.pub';
+    const stored = existsSync(pub) ? readFileSync(pub, 'utf8').trim() : undefined;
+    if (stored === undefined || keyMaterial(stored) !== keyMaterial(derived)) {
+        writeFileAtomicSync(pub, derived + '\n', { mode: 0o644 });
+    }
+    return derived;
+}
+/** `<type> <blob>` of a public-key record, comment dropped. */
+const keyMaterial = (record) => record.split(/\s+/).slice(0, 2).join(' ');
+async function mintCert(api, projectId, serviceId, publicKey, alias, signal) {
+    const res = await api.rawRequest('POST', `/projects/${projectId}/services/${serviceId}/ssh-cert`, { publicKey }, { signal });
+    if (res.status < 200 || res.status >= 300) {
+        throw new ApiError(res.status, res.body?.error ?? 'could not issue an ssh certificate');
+    }
+    // Validated BEFORE the write, not after. The certificate file is the live
+    // credential for an alias that may already be working, so a response we go
+    // on to reject must not have replaced it on the way -- the caller would be
+    // left with an error message and a broken alias. Same ordering rule as the
+    // collision check: nothing is written until the whole response is known-good.
+    const out = validateCertResponse(res.body);
+    return { ...out, staged: stageCertificate(instaCertPath(alias), out.certificate.trim() + '\n', { publicKey }) };
+}
+/** Everything the plane returns that we will write into ~/.ssh or ~/.insta. */
+export function validateCertResponse(body) {
+    const b = (body ?? {});
+    // The CONTENT, not merely the presence. A non-empty string was enough to
+    // replace a working alias's live credential with something OpenSSH cannot
+    // parse -- failing later, inside ssh, with a message pointing at the file
+    // rather than at the plane that sent it.
+    if (!isSSHCertificateRecord(b.certificate)) {
+        throw new Error('the platform did not return a usable ssh certificate');
+    }
+    if (!isSafeConfigValue(b.host) || !isSafeSSHHost(b.host)) {
+        throw new Error(`the platform returned an unusable ssh host: ${JSON.stringify(String(b.host).slice(0, 64))}`);
+    }
+    // Principal syntax, which above all excludes a leading `-`: the printed
+    // command is argv for `ssh`, and `ssh` parses its own options no matter how
+    // the shell quoted them.
+    if (!isSafeSSHUsername(b.username)) {
+        throw new Error(`the platform returned an unusable ssh username: ${JSON.stringify(String(b.username).slice(0, 64))}`);
+    }
+    // Printed straight to a terminal, so control characters and escape sequences
+    // are refused rather than rendered.
+    if (!isSafeTimestamp(b.expiresAt))
+        throw new Error('the platform returned an unusable certificate expiry');
+    // Parsed here rather than at install time so a malformed key fails before
+    // anything is written, instead of after the alias is already recorded.
+    if (b.caPublicKey !== undefined)
+        parseCAPublicKey(b.caPublicKey);
+    return b;
+}
+const sshKeygenVerifyCert = (certPath) => {
+    execFileSync('ssh-keygen', ['-L', '-f', certPath], { stdio: 'ignore' });
+};
+/**
+ * Write a certificate into staging only once OpenSSH agrees it is one.
+ *
+ * The structural decode in isSSHCertificateRecord reads the blob's first field
+ * and stops. That rejects arbitrary base64, and it still accepts a blob whose
+ * type name is right and whose remaining bytes are noise -- there is no nonce,
+ * public key, serial, principal list, validity window or signature behind it.
+ * Such a response would replace a WORKING alias's live credential and fail
+ * later inside ssh, which is exactly the preservation guarantee this command
+ * makes.
+ *
+ * So the authority is `ssh-keygen -L`, run against a temporary file, and the
+ * real file is only replaced once it passes. Spawning it here costs nothing
+ * new: certNeedsRenewal already runs the same binary on this same path, every
+ * time a certificate exists. (An earlier round declined this on the grounds
+ * that a subprocess did not belong on the renewal path -- that reasoning was
+ * simply wrong about what the path already does.)
+ *
+ * A missing ssh-keygen is a REFUSAL, not a pass: it means we cannot confirm,
+ * and an unconfirmable certificate must not displace one that works. Nothing
+ * is lost by it either -- without OpenSSH installed the certificate has no
+ * consumer.
+ */
+export function stageCertificate(certPath, contents, { verify = sshKeygenVerifyCert, publicKey } = {}) {
+    // BEFORE the file is even written, because this needs no file: `ssh-keygen -L`
+    // proves the response is a certificate, not that it is a certificate for the
+    // key we asked about. One issued for another key passes every other gate and
+    // fails at authentication time instead -- after the working credential is
+    // already gone.
+    if (publicKey !== undefined && !certifiesPublicKey(contents, publicKey)) {
+        throw new Error('the platform returned a certificate for a different key — the existing certificate was left untouched');
+    }
+    mkdirSync(dirname(certPath), { recursive: true, mode: 0o700 });
+    // Followed to its target, for the same reason writeFileAtomicSync does it:
+    // rename(2) replaces the LINK, so a certificate someone symlinked into a
+    // dotfiles repo would be severed on the first renewal -- quietly, and only
+    // on the path that runs unattended.
+    const target = resolveThroughSymlink(certPath);
+    const staging = `${target}.staging-${process.pid}-${randomUUID()}`;
+    const discard = () => {
+        try {
+            unlinkSync(staging);
+        }
+        catch { /* committed, or never created */ }
+    };
+    try {
+        writeFileSync(staging, contents, { mode: 0o644 });
+    }
+    catch (e) {
+        discard();
+        throw e;
+    }
+    try {
+        verify(staging);
+    }
+    catch (e) {
+        discard();
+        const why = e?.code === 'ENOENT'
+            ? 'ssh-keygen is not installed, so the certificate cannot be checked'
+            : 'the platform returned a certificate OpenSSH cannot parse';
+        throw new Error(`${why} — the existing certificate was left untouched`);
+    }
+    return { commit: () => renameSync(staging, target), discard };
+}
+/** One line covers every node in every region, which is the whole reason for a
+ *  host CA: the TOFU alternative is a fingerprint per node and a REMOTE HOST
+ *  IDENTIFICATION HAS CHANGED for a random fraction of reconnects behind a load
+ *  balancer. Re-run on every renewal too, so a rotated CA is trusted before the
+ *  retired one stops signing rather than at the user's next `--setup`. */
+export function installCertAuthority(hostPattern, caPublicKey) {
+    const knownHosts = userKnownHostsPath();
+    // The read and the write are ONE operation, and the lock is what makes them
+    // one. Without it two aliases renewing together both read these contents and
+    // each renames its own result over the other's -- see withKnownHostsLock.
+    return withKnownHostsLock(() => {
+        mkdirSync(dirname(knownHosts), { recursive: true, mode: 0o700 });
+        const existedBefore = pathExists(knownHosts);
+        const existing = readUserText(knownHosts);
+        const plan = planCertAuthority(existing, hostPattern, caPublicKey);
+        if (plan.next === existing)
+            return () => { };
+        writeFileAtomicSync(knownHosts, plan.next, { mode: 0o600 });
+        // A ROTATION retires the anchor that vouches for the certificate currently
+        // installed, and the steps that follow it -- the config write, the
+        // certificate rename -- can still fail. Without a way back, a failed
+        // command leaves the old certificate in place with its CA gone: an alias
+        // that worked a moment ago now cannot authenticate, and nothing said so.
+        return () => withKnownHostsLock(() => {
+            const reverted = revertCertAuthority(readUserText(knownHosts), plan);
+            // A file this command CREATED and would now leave empty goes away with
+            // the anchor: a failed first setup must not leave an empty known_hosts
+            // behind as its only trace. One `ssh` has since written to stays.
+            if (!existedBefore && reverted === '') {
+                try {
+                    unlinkSync(knownHosts);
+                }
+                catch { /* never created */ }
+            }
+            else {
+                writeFileAtomicSync(knownHosts, reverted, { mode: 0o600 });
+            }
+        });
+    });
+}
+/** The SSHDeps seam lets a test stub return anything at all, so what comes back
+ *  is checked here rather than trusted. */
+function record(undo, back) {
+    if (typeof back === 'function')
+        undo.push(back);
+}
+/** Run `steps` in order; when one throws, take back the ones before it in
+ *  reverse and rethrow. Every step that can be taken back returns how, because
+ *  the steps AFTER an anchor rotation can still fail and the rotation is what
+ *  retires the CA vouching for the certificate already installed. Undone in
+ *  reverse so each step sees the world its own undo expects.
+ *
+ *  Undo failures are swallowed on purpose: the error that got us here is the
+ *  one worth reporting, and an undo that cannot run leaves exactly the state
+ *  we would have had without one. */
+function commitWithUndo(steps) {
+    const undo = [];
+    try {
+        for (const step of steps)
+            record(undo, step());
+    }
+    catch (e) {
+        for (const back of undo.reverse()) {
+            try {
+                back();
+            }
+            catch { /* nothing better to do on the way out */ }
+        }
+        throw e;
+    }
+}
+/** How long an anchor update waits for another insta process before giving up.
+ *  Short, because this still runs inside OpenSSH's config parse: a caller that
+ *  cannot get in gives the renewal up and the login proceeds on the certificate
+ *  already installed, which is strictly better than making `ssh` wait. */
+const KNOWN_HOSTS_LOCK_WAIT_MS = 1_000;
+const LOCK_POLL_MS = 20;
+/** The locks that guard FILES break only when their holder's process is gone,
+ *  never on age -- see isAbandoned for why a slow holder must stay a holder. */
+const FILE_LOCK_STALE_MS = Infinity;
+/** Sleep without yielding to the event loop, which is what the callers here
+ *  want: the section being waited for is synchronous. */
+const sleepSync = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+/**
+ * Hold the shared-file lock across a read-modify-write of ~/.ssh/known_hosts.
+ *
+ * The renewal lock is per ALIAS; known_hosts is ONE file every alias writes to.
+ * Two aliases expiring together — the ordinary case for a project with two
+ * compute services — therefore read the same contents, each edits its own copy
+ * and each renames over the other. The loser's anchor is gone, and its
+ * certificate has already been issued against a CA that is no longer trusted:
+ * during a rotation that alias simply stops connecting, with nothing said. The
+ * same window discards unrelated lines the user's own editor had just added.
+ *
+ * It WAITS, unlike the renewal lock, because what is at stake is a lost anchor
+ * rather than a duplicate request. The wait is bounded and short, and a caller
+ * that cannot get in gives the whole renewal up, which leaves the previous
+ * certificate — and the CA that signed it — in place.
+ *
+ * It covers insta processes. `ssh` appends host keys to the same file without
+ * any lock and cannot be made to take one; that window is inherent to
+ * known_hosts and is narrowed here, not closed.
+ *
+ * RE-ENTRANT, because the callers that matter hold it across a whole
+ * transaction and installCertAuthority takes it again from inside — see the
+ * depth counter below.
+ */
+export function withKnownHostsLock(fn, { waitMs = KNOWN_HOSTS_LOCK_WAIT_MS, sleep = sleepSync } = {}) {
+    if (knownHostsLockDepth > 0)
+        return fn();
+    return withLockedFile('known_hosts.lock', () => {
+        knownHostsLockDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            knownHostsLockDepth--;
+        }
+    }, {
+        waitMs,
+        sleep,
+        staleMs: FILE_LOCK_STALE_MS,
+        busy: 'another insta process is updating ~/.ssh/known_hosts, so the trust anchor was left as it was',
+    });
+}
+/** How deep THIS process is inside the known_hosts lock.
+ *
+ *  A transaction holds the lock and then calls installCertAuthority, which
+ *  takes it again; on an exclusive-create lock file that is a self-deadlock,
+ *  and one that resolves as the busy error rather than a hang, so it would read
+ *  as "another process is updating known_hosts" when the other process is us.
+ *
+ *  A plain counter is enough because every section it guards is synchronous:
+ *  nothing else in this process can run between the increment and the
+ *  decrement, so the count cannot be observed mid-flight or left behind by an
+ *  interleaved caller. */
+let knownHostsLockDepth = 0;
+/** How long a setup waits for another setup. Longer than the known_hosts wait
+ *  because the section it guards CONTAINS that wait, plus two file writes. */
+const ALIAS_STORE_LOCK_WAIT_MS = 10_000;
+/**
+ * Hold a lock across the whole read-modify-write of the alias store AND the
+ * ssh_config block rendered from it.
+ *
+ * These are one transaction, not two files that happen to be written together:
+ * the config block is rendered from the WHOLE store, so a stale read produces a
+ * config missing somebody else's alias. Two `--setup` runs for different
+ * services -- a project with an `api` and a `worker` is the ordinary case --
+ * both read the same aliases.json, each adds only its own entry, and each
+ * writes both files. Whichever finished second wins outright: the other alias
+ * is gone from the store and from the config, and BOTH commands printed the
+ * alias they had configured.
+ *
+ * It waits rather than giving up, because the loser of the race is a lost
+ * alias, and it is the caller's job to re-read the store once inside — see
+ * computeSSH, where the collision check runs again under the lock.
+ */
+export function withAliasStoreLock(fn, { waitMs = ALIAS_STORE_LOCK_WAIT_MS, sleep = sleepSync } = {}) {
+    return withLockedFile('aliases.lock', fn, {
+        waitMs,
+        sleep,
+        staleMs: FILE_LOCK_STALE_MS,
+        busy: 'another insta process is setting up an ssh alias, so nothing was changed. Try again in a moment',
+    });
+}
+/** Hold a named lock in ~/.insta/ssh for the duration of `fn`, waiting for it.
+ *
+ *  LOCK ORDER, and it is the whole reason this is one helper: a caller that
+ *  needs both takes `aliases.lock` FIRST and `known_hosts.lock` inside it.
+ *  Nothing acquires them the other way round, so the pair cannot deadlock. */
+function withLockedFile(name, fn, { waitMs, staleMs, sleep, busy }) {
+    const path = join(instaSSHDir(), name);
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        const release = acquireLockFile(path, Date.now(), staleMs);
+        if (release) {
+            try {
+                return fn();
+            }
+            finally {
+                release();
+            }
+        }
+        // Named, because a lock whose holder cannot be shown dead (a pid reused by
+        // an unrelated process, a home shared from another machine) stays busy on
+        // purpose, and the way out is the user's to take.
+        if (Date.now() >= deadline)
+            throw new Error(`${busy} (if no other insta is running, remove ${path})`);
+        sleep(LOCK_POLL_MS);
+    }
+}
+function installConfigBlock(store) {
+    const cfg = join(homedir(), '.ssh', 'config');
+    mkdirSync(dirname(cfg), { recursive: true, mode: 0o700 });
+    // EXISTENCE and CONTENTS are tracked apart, because an empty file is not a
+    // missing one and the undo below does opposite things for the two. A
+    // dotfiles-managed ~/.ssh/config symlinked at a target that has not been
+    // populated yet reads as '' exactly like a file we are about to create.
+    // lstat, not existsSync: a link is something that was there, whatever its
+    // target says.
+    const existedBefore = pathExists(cfg);
+    const existing = readUserText(cfg);
+    const block = renderConfigBlock({
+        entries: hostEntries(store),
+        identityFile: instaKeyPath(),
+        knownHostsFile: userKnownHostsPath(),
+        ensureCertCommand: ENSURE_CERT_COMMAND,
+    });
+    // Backed up: this is the file that decides whether the user can ssh anywhere
+    // at all, and our block goes at the TOP of it.
+    writeFileAtomicSync(cfg, upsertConfigBlock(existing, block), { mode: 0o600, backup: true });
+    // Safe to restore wholesale, unlike known_hosts: nothing else writes this
+    // file without the alias-store lock, and the caller holds it.
+    return () => {
+        if (!existedBefore) {
+            try {
+                unlinkSync(cfg);
+            }
+            catch { /* never created */ }
+        }
+        else {
+            // Through the SAME symlink-aware writer as the forward write, so an
+            // existing file is restored where the block was actually written --
+            // restoring the link's target rather than replacing the link.
+            writeFileAtomicSync(cfg, existing, { mode: 0o600 });
+        }
+    };
+}
+/** Is there a live ssh_config block backing the alias store right now?
+ *
+ *  Read under the alias-store lock, like every other access to this file, so it
+ *  cannot observe a half-written block. A config we cannot read at all counts
+ *  as no block: the answer only ever ADDS writes, so the safe way to be wrong
+ *  is to leave ~/.ssh alone. */
+function configBlockInstalled() {
+    try {
+        return hasOwnedBlock(readFileSync(join(homedir(), '.ssh', 'config'), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+/** Does this path name anything at all -- file, directory or symlink, including
+ *  one that dangles? `existsSync` follows links and so answers a different
+ *  question: it calls a link to a missing target "not there", and deleting on
+ *  that answer destroys the link. */
+function pathExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** How to put a file back exactly as it is now: its bytes, or its absence.
+ *
+ *  The BYTES, not readAliasStore's reading of them. The reader drops entries
+ *  it cannot use, on purpose, so an undo that wrote the reader's output back
+ *  would delete a hand-edited entry the user was about to fix and turn a store
+ *  that never existed into `{}` -- on the failure path, where the command has
+ *  just promised it changed nothing. */
+function snapshotForUndo(path) {
+    const existed = pathExists(path);
+    let bytes;
+    if (existed) {
+        try {
+            bytes = readFileSync(path);
+        }
+        catch {
+            bytes = undefined;
+        }
+    }
+    return () => {
+        if (!existed) {
+            try {
+                unlinkSync(path);
+            }
+            catch { /* never created */ }
+        }
+        else if (bytes !== undefined) {
+            writeFileAtomicSync(path, bytes, { mode: 0o600 });
+        }
+    };
+}
+/** The text of a user-owned file this command is about to rewrite, or '' when
+ *  there is none -- REFUSING one that is not UTF-8. Decoding such a file and
+ *  writing it back turns every byte that did not decode into U+FFFD: a
+ *  Latin-1 comment in a twenty-year-old ~/.ssh/config would be rewritten,
+ *  silently, by a command that promised to add one block at the top. */
+function readUserText(path) {
+    if (!existsSync(path))
+        return '';
+    const raw = readFileSync(path);
+    const text = raw.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(raw)) {
+        throw new Error(`refusing to edit ${path}: it is not valid UTF-8, and rewriting it would alter bytes this command does not own`);
+    }
+    return text;
+}
+/**
+ * The renewal hook OpenSSH runs while PARSING the config, before it connects.
+ *
+ * Two properties, both load-bearing, and both about the fact that this runs on
+ * EVERY ssh invocation — including `scp`, `ssh -G` and an IDE's connections:
+ *
+ *  - Cheap when there is nothing to do. The local certificate is checked FIRST;
+ *    a valid one returns before any config, project or API work happens. This
+ *    is also why the config block invokes the HIDDEN `__ssh-ensure-cert`
+ *    command rather than `compute ssh --ensure-cert`: `guard` awaits
+ *    trackCommand() after every action, which reads global and project config,
+ *    can create ~/.insta/telemetry.json and issues a PostHog request with a
+ *    timeout of up to 1.5s. Returning early from the action does not skip any
+ *    of that. Telemetry already skips command paths beginning `__` (the same
+ *    rule __update-check relies on), so the fast path is genuinely local only
+ *    when the hook enters through that name.
+ *  - Silent and fail-safe. An unlinked directory, an expired login or a network
+ *    outage must not print anything or fail the parse: the existing certificate
+ *    stays in place and the login then fails with SSH's own message, not a CLI
+ *    error spliced into the middle of an ssh session.
+ */
+export async function ensureCertForAlias(alias, timeoutMs = RENEWAL_REQUEST_TIMEOUT_MS) {
+    let release;
+    try {
+        if (!isSafeAlias(alias))
+            return;
+        if (!certNeedsRenewal(instaCertPath(alias)))
+            return;
+        // An IDE opens several connections at once and `scp` adds more, so the
+        // near-expiry certificate is observed by every one of them simultaneously
+        // and each would mint its own replacement -- redundant requests against a
+        // rate-limited endpoint, racing each other's known_hosts writes.
+        //
+        // NON-BLOCKING on purpose: losing the race returns immediately rather than
+        // waiting. This runs inside OpenSSH's config parse, so a lock that waits is
+        // a lock that can hang `ssh` itself -- strictly worse than the duplicate
+        // request it would prevent. The loser simply lets the winner renew.
+        release = acquireRenewalLock(alias);
+        if (!release)
+            return;
+        // Re-checked after the lock. Without this the second process through the
+        // door renews again over the certificate the first just wrote -- the lock
+        // would serialise the stampede instead of collapsing it.
+        if (!certNeedsRenewal(instaCertPath(alias)))
+            return;
+        // The alias is the ONLY input: it carries the project, branch and service
+        // the certificate was issued for, so renewal cannot drift to another one.
+        const rec = readAliasStore()[alias];
+        if (!rec)
+            return;
+        const api = await ApiClient.load();
+        // A DEADLINE, because this runs inside OpenSSH's config parse. A server
+        // that accepts the connection and then says nothing would otherwise block
+        // ssh, scp, `ssh -G` and every IDE connection for as long as it liked --
+        // the catch below only helps once the request has actually rejected.
+        // AbortSignal rather than a Promise.race: a race returns while leaving the
+        // socket open, so the process lingers anyway.
+        const out = await mintCert(api, rec.projectId, rec.serviceId, ensureKeyPair(), alias, AbortSignal.timeout(timeoutMs));
+        try {
+            // The commit is a setup transaction in miniature, under the SAME lock a
+            // setup holds -- aliases.lock -- and for two reasons.
+            //
+            // A renewal can MOVE the alias. The response names the host and the
+            // principal this certificate was issued for, and the installed stanza
+            // routes on the ones recorded at setup. Committing the certificate alone
+            // left `ssh <alias>` connecting to yesterday's host as yesterday's user
+            // carrying a certificate that names today's -- while anchoring today's
+            // host, since the anchor below is derived from the response. So the
+            // store and, where the block is installed, the config move with the
+            // certificate, exactly as a plain re-issue does in computeSSH.
+            //
+            // And the mint ran OUTSIDE any lock (no network under a lock), so the
+            // world is re-read in here. A `--setup` that finished meanwhile may have
+            // replaced the certificate with a newer one, and a stale mint must not
+            // undo that; a record removed or re-pointed meanwhile is one this
+            // certificate was not issued for.
+            //
+            // Lock order stays acyclic: the per-alias renewal lock is only ever
+            // taken first, and only by renewals; then aliases.lock; then
+            // known_hosts.lock inside it. The wait is the SHORT one, because this
+            // still runs inside OpenSSH's config parse: a renewal that cannot get in
+            // gives up whole, leaving the certificate and the anchor it found.
+            withAliasStoreLock(() => {
+                const before = readAliasStore();
+                const held = before[alias];
+                if (!held || held.projectId !== rec.projectId || held.serviceId !== rec.serviceId)
+                    return;
+                if (!certNeedsRenewal(instaCertPath(alias)))
+                    return;
+                const moved = held.host !== out.host || held.username !== out.username;
+                const store = moved
+                    ? { ...before, [alias]: { ...held, host: out.host, username: out.username } }
+                    : before;
+                const installed = configBlockInstalled();
+                const ca = out.caPublicKey;
+                // A move that may need a NEW anchor is a setup-grade change, and a
+                // response that moves the host but carries no CA cannot complete it:
+                // going ahead would route the alias to a host nothing in known_hosts
+                // vouches for -- a host-key prompt on every connection, the failure the
+                // anchor exists to prevent -- while reporting nothing. Abandoned whole,
+                // exactly as `--setup` refuses without a CA: the alias keeps what it
+                // has, and the next `--setup` repairs it. An unmoved renewal without a
+                // CA still goes ahead, because its anchor is already installed.
+                if (moved && installed && ca === undefined)
+                    return;
+                // The ANCHOR before the certificate. Committing the certificate first
+                // left the alias holding a credential signed by a CA this machine does
+                // not trust whenever the anchor write failed -- and the catch below
+                // would have swallowed that too. The rename that ends it is the step
+                // that does not fail halfway, but it can still fail outright, and on a
+                // ROTATION that leaves the retired CA gone with the certificate it
+                // signed still installed -- so every step before it is taken back.
+                //
+                // The config is re-rendered only when something in it CHANGES. OpenSSH
+                // is reading that very file right now; POSIX lets a rename replace an
+                // open file, Windows does not, and there the undo chain turns a moved
+                // host into a renewal that gives up -- one failed renewal and a
+                // `--setup` to repair it, never a half-moved alias.
+                const steps = [];
+                if (moved)
+                    steps.push(() => { const back = snapshotForUndo(instaAliasStorePath()); writeAliasStore(store); return back; });
+                if (ca !== undefined)
+                    steps.push(() => installCertAuthority(hostPatternFor(out.host), ca));
+                if (moved && installed)
+                    steps.push(() => installConfigBlock(store));
+                steps.push(() => out.staged.commit());
+                // ONE section from reading the anchor to committing the certificate
+                // that depends on it, rollback included -- see the note in computeSSH.
+                if (ca !== undefined)
+                    withKnownHostsLock(() => commitWithUndo(steps));
+                else
+                    commitWithUndo(steps);
+            }, { waitMs: KNOWN_HOSTS_LOCK_WAIT_MS });
+        }
+        finally {
+            out.staged.discard();
+        }
+    }
+    catch {
+        // Deliberately swallowed. See above.
+    }
+    finally {
+        release?.();
+    }
+}
+/** A renewal lock older than this is broken even if its holder is alive. That
+ *  is safe HERE and nowhere else -- see isAbandoned: what it guards is a
+ *  duplicate request, and a wedged renewal lock would silently stop one alias
+ *  renewing, which is a worse failure than a duplicate mint. */
+const RENEWAL_LOCK_STALE_MS = 60_000;
+/** How long the renewal request may take before it is abandoned. Sized for the
+ *  path it sits on: OpenSSH is parsing its config and the user is waiting, so a
+ *  renewal that cannot finish quickly is better skipped -- the existing
+ *  certificate is still in place and the login proceeds on it. */
+const RENEWAL_REQUEST_TIMEOUT_MS = 5_000;
+/** Take the per-alias renewal lock, or return undefined if someone else holds
+ *  a fresh one. Never waits — see the call site. */
+export function acquireRenewalLock(alias, now = Date.now()) {
+    return acquireLockFile(join(instaSSHDir(), `${alias}.renew.lock`), now, RENEWAL_LOCK_STALE_MS);
+}
+/** Take a lock file, or return undefined when someone else holds it.
+ *  Never waits: whether waiting is the right answer depends on what is being
+ *  protected, so it belongs to the caller.
+ *
+ *  A lock is `${pid}:${uuid}` in a file created with O_EXCL. It is BROKEN --
+ *  taken over from a holder that will never release it -- under isAbandoned's
+ *  rule, and the takeover never unlinks the path: see breakStaleLock.
+ *
+ *  Exported for the concurrency tests. `now` and `staleMs` are the AGE rule:
+ *  the locks that guard files pass Infinity, the renewal lock a minute, and
+ *  the tests whatever window they need to cross. */
+export function acquireLockFile(path, now, staleMs) {
+    // A token, not just the pid. A renewal slower than the staleness window has
+    // its lock broken by the next caller; without an ownership check the
+    // original holder's release would then delete the NEW holder's lock, leaving
+    // the file unlocked while two renewals ran -- the lock defeating itself
+    // precisely when it is under load. The pid is in it so a later caller can
+    // ask whether the holder still exists.
+    const token = `${process.pid}:${randomUUID()}`;
+    const release = () => {
+        try {
+            if (readFileSync(path, 'utf8') === token)
+                unlinkSync(path);
+        }
+        catch { /* already gone, or taken over by someone else */ }
+    };
+    const take = () => {
+        try {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            // wx is the atomic part: exclusive create fails if the file exists, so
+            // exactly one process can win regardless of how many arrive together.
+            writeFileSync(path, token, { flag: 'wx', mode: 0o600 });
+            return release;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const held = take();
+    if (held)
+        return held;
+    // A lock path that is a LINK is refused before anything reads or writes
+    // through it. `wx` already refuses to create over a link, and the takeover
+    // below writes into the inode the path names -- through a link that is
+    // somebody else's file.
+    if (isSymlink(path))
+        return undefined;
+    const observed = observeLock(path);
+    // Released between the exclusive create and the read: ordinary contention,
+    // and `wx` is the only arbiter that needs to settle it. Nothing is being
+    // taken from anybody here, so retrying is safe.
+    if (!observed)
+        return take();
+    if (!isAbandoned(observed, now, staleMs))
+        return undefined;
+    return breakStaleLock(path, observed.token, token) ? release : undefined;
+}
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** The lock as one consistent observation: the token that is in the file and
+ *  the mtime that goes with it. */
+function observeLock(path) {
+    try {
+        // CONTENTS FIRST, and the order is the point. A takeover landing between
+        // the two reads then pairs the OLD token with the NEW mtime, and the
+        // staleness test refuses to break it -- the safe way to be wrong. Read the
+        // other way round it pairs an old mtime with the new holder's token, and
+        // the takeover proceeds against a lock that was taken a moment ago.
+        const token = readFileSync(path, 'utf8');
+        return { token, mtimeMs: statSync(path).mtimeMs };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a lock may be taken from its holder.
+ *
+ *  The holder's PROCESS is the first question, and for the locks that guard
+ *  files it is the only one. A holder that is merely SLOW is still a holder:
+ *  judging it by the age of its lock and breaking it admits a second writer to
+ *  aliases.json, ssh_config or known_hosts while the first is still inside the
+ *  section -- and, worse, still able to RELEASE, which is what made the old
+ *  takeover racy: its release between the breaker's check and the breaker's
+ *  act let a third process create a fresh lock there for the breaker to
+ *  destroy. A holder whose process is GONE can do neither, and that is what
+ *  makes breaking its lock safe. Those callers pass `staleMs = Infinity`: they
+ *  never break a live holder, and when a pid cannot be judged -- a lock taken
+ *  from another machine sharing the home, a pid reused by an unrelated process
+ *  -- they stay busy and name the file to remove.
+ *
+ *  The renewal lock ALSO breaks by age, because what it guards is a duplicate
+ *  request rather than a file: two renewals that both get through each commit
+ *  under aliases.lock, where the second finds a fresh certificate and gives
+ *  up. A wedged renewal lock, on the other hand, silently stops one alias
+ *  renewing, so it must not depend on a pid that may be unjudgeable.
+ *
+ *  A lock with no readable pid -- a process that died between the exclusive
+ *  create and the write, or a hand-edited file -- can never be released by
+ *  anyone, and is judged by age against a bound no live creator could spend
+ *  between two consecutive syscalls. */
+function isAbandoned({ token, mtimeMs }, now, staleMs) {
+    const pid = holderPid(token);
+    if (pid !== undefined && !processAlive(pid))
+        return true;
+    const bound = pid === undefined ? Math.min(staleMs, ORPHAN_LOCK_STALE_MS) : staleMs;
+    return now - mtimeMs >= bound;
+}
+/** How old a lock with no readable owner must be before it is broken. */
+const ORPHAN_LOCK_STALE_MS = 60_000;
+function holderPid(token) {
+    const m = /^(\d+):/.exec(token);
+    const pid = m ? Number(m[1]) : NaN;
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+}
+/** Whether a process with this pid exists on this machine. EPERM means it
+ *  exists and is not ours; anything but ESRCH is "cannot tell", which reads as
+ *  alive -- cannot-confirm is not a licence to take somebody's lock. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code !== 'ESRCH';
+    }
+}
+/** Take over the lock `stale` names, having judged it abandoned, by writing
+ *  `mine` into it. True when `path` now carries `mine`.
+ *
+ *  Two things have to hold at once, and the two primitives are chosen for
+ *  exactly them.
+ *
+ *  Breaking a lock is itself mutually exclusive. Every contender that finds
+ *  the same dead holder's lock passes isAbandoned together, and without a
+ *  serialisation point the first to act takes a fresh lock and the ones behind
+ *  it destroy THAT and take their own -- the lock admitting everybody
+ *  precisely when it is contended. So the right to break is claimed with a
+ *  HARDLINK named after the token being broken: link(2) is atomic and fails
+ *  with EEXIST, so of all the contenders that observed this token exactly one
+ *  proceeds; and it is non-destructive -- a hardlink adds a name, it does not
+ *  move or remove the lock, so there is no window in which the file is
+ *  missing for something to slip in through.
+ *
+ *  And the takeover NEVER UNLINKS THE PATH. The first version verified the
+ *  token, unlinked the lock and created its own, and nothing tied that unlink
+ *  to the inode it had verified: a holder releasing in between let a third
+ *  process create a fresh lock at the path, which the breaker then deleted.
+ *  Here the breaker writes its token INTO the inode the two names share.
+ *  `path` keeps its inode throughout, so there is no moment at which the lock
+ *  at `path` can have become somebody else's between the check and the act:
+ *  the holder judged dead cannot release, every other breaker is behind the
+ *  claim, and a release by anyone else checks for its own token first. Should
+ *  the old holder's release ever run, it reads a foreign token and leaves the
+ *  file alone.
+ *
+ *  Residual, and deliberately not "fixed": a breaker killed between the link
+ *  and its write leaves the claim behind, and that one token can then no
+ *  longer be broken (removing the claim by hand is the way out, and the busy
+ *  message names the lock). Every scheme for reaping an abandoned claim needs
+ *  to decide the claim is dead and then remove it -- the same check-then-act
+ *  this function exists to eliminate, one level up. A claim left behind AFTER
+ *  the write is inert: the lock now carries the breaker's token, and the next
+ *  breaker keys its claim on that. A wedged lock is recoverable and says so;
+ *  two writers in the same section silently lose the user's config. */
+function breakStaleLock(path, stale, mine) {
+    const claim = `${path}.stale.${createHash('sha256').update(stale).digest('hex').slice(0, 32)}`;
+    try {
+        linkSync(path, claim);
+    }
+    catch {
+        // EEXIST: somebody else is already breaking this one. ENOENT: it is gone.
+        // Anything else (a filesystem with no hardlinks) means we cannot establish
+        // who is entitled to break it -- and cannot-establish is not a licence to
+        // take somebody's lock. Failing closed costs a renewal that gets skipped
+        // or a `--setup` that reports the file as busy; failing open costs the
+        // user's ssh_config. The caller retries if it waits.
+        return false;
+    }
+    try {
+        // Still the lock that was judged abandoned: tokens are unique per
+        // acquisition, so a takeover in between shows up as different bytes.
+        if (readFileSync(path, 'utf8') !== stale)
+            return false;
+        writeFileSync(claim, mine);
+        // Read back through `path`, the name everybody else uses: the lock is ours
+        // only if that is what they will see.
+        return readFileSync(path, 'utf8') === mine;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            unlinkSync(claim);
+        }
+        catch { /* the inode keeps its other name */ }
+    }
+}
+export async function computeSSH(serviceName, opts, deps = {}) {
+    if (opts.ensureCert !== undefined)
+        return ensureCertForAlias(opts.ensureCert);
+    const mint = deps.mint ?? mintCert;
+    const emit = deps.emit ?? info;
+    const api = await (deps.loadApi ?? ApiClient.load)();
+    const p = await (deps.loadProject ?? requireProject)();
+    const branch = opts.branch ?? p.branch;
+    const { services } = await api.request('GET', `/projects/${p.projectId}/services${q(branch)}`);
+    const svc = resolveSoleService(services, 'compute', serviceName);
+    const alias = aliasFor(svc.name);
+    // BEFORE the mint, and the order is the fix. mintCert writes
+    // `<alias>-cert.pub` as part of succeeding, so checking afterwards meant a
+    // collision had already overwritten the certificate of the alias it was
+    // about to refuse -- the previously working `api.insta` could no longer
+    // authenticate, and the command that broke it exited with an error saying it
+    // had done nothing. Nothing is written until the alias is known to be ours.
+    assertAliasFree(readAliasStore(), alias, { projectId: p.projectId, serviceId: svc.id, branch });
+    const out = await mint(api, p.projectId, svc.id, (deps.keyPair ?? ensureKeyPair)(), alias);
+    /** Whether ~/.ssh ends up describing this alias — decided under the lock, and
+     *  the only honest basis for advertising `ssh <alias>`. */
+    let installed = false;
+    try {
+        // --setup PROMISES a trust anchor, so a response without one cannot be
+        // reported as configured. Skipping installCA and carrying on left plain
+        // `ssh`/`scp` facing a host-key prompt on every new node behind the load
+        // balancer -- the exact failure the anchor exists to prevent -- while the
+        // command printed the short alias and claimed success. Checked before
+        // anything is installed, so the refusal is clean.
+        if (opts.setup && !out.caPublicKey) {
+            throw new Error('the platform did not return an ssh certificate authority key, so `--setup` cannot install the trust anchor it promises.\n' +
+                'Retry, and contact support if it persists; the certificate itself was issued and `insta compute ssh ' + svc.name + '` still prints a usable command.');
+        }
+        // ALL of it under one lock, and the store is re-read inside: the check
+        // above ran before the mint, which is where it has to be to avoid
+        // overwriting the certificate of an alias it is about to refuse -- but the
+        // network round trip between them is easily long enough for another setup
+        // to claim the alias, or to add one of its own that a stale store would
+        // then erase from both files.
+        withAliasStoreLock(() => {
+            const before = readAliasStore();
+            assertAliasFree(before, alias, { projectId: p.projectId, serviceId: svc.id, branch });
+            const store = {
+                ...before,
+                [alias]: { projectId: p.projectId, ...(branch ? { branch } : {}), serviceId: svc.id, host: out.host, username: out.username },
+            };
+            // Whether ~/.ssh is BACKING this store, not merely whether --setup was
+            // passed. The store and the certificate are rewritten by every issuance,
+            // `--setup` or not; the config block and the anchor used to be rewritten
+            // only by `--setup`. So a plain re-issue that came back with a moved
+            // host, a renamed principal or a rotated CA updated half of what an
+            // installed `ssh api.insta` depends on and left the rest describing
+            // yesterday -- the alias went on routing to the old host holding a
+            // certificate minted for the new one, and the command printed success.
+            //
+            // Once the block exists it is a rendering of the whole store, so any
+            // store write has to re-render it. All four artifacts then move together
+            // under the one lock, with the same undo chain as a setup.
+            installed = opts.setup || (deps.configInstalled ?? configBlockInstalled)();
+            // Every step that can be taken back registers how -- see commitWithUndo.
+            const ca = out.caPublicKey;
+            const steps = [
+                () => { const back = snapshotForUndo(instaAliasStorePath()); writeAliasStore(store); return back; },
+            ];
+            if (installed) {
+                // planCertAuthority parses the key and refuses a bad one, so a hostile
+                // or malformed response fails HERE instead of appending lines to
+                // known_hosts.
+                if (ca)
+                    steps.push(() => (deps.installCA ?? installCertAuthority)(hostPatternFor(out.host), ca));
+                steps.push(() => (deps.installConfig ?? installConfigBlock)(store));
+            }
+            // Last, and for the same reason as in the renewal hook: a certificate
+            // whose anchor never landed authenticates nothing, so it does not
+            // replace one that still works.
+            steps.push(() => out.staged.commit());
+            const commitAll = () => commitWithUndo(steps);
+            // The ROLLBACK is inside the anchor's lock too, not just the write it
+            // takes back. Holding the lock per edit and dropping it before the
+            // transaction settled made the undo a decision about a file someone else
+            // had meanwhile committed against: this command rotates CA_PREV to CA and
+            // keeps an undo restoring CA_PREV; a renewal arriving after that write
+            // sees CA already anchored, is handed a do-nothing undo for it, and
+            // commits a certificate signed by CA; this command then fails, its undo
+            // retires CA -- and the renewal's certificate, minted and committed
+            // perfectly correctly, now authenticates nothing. The renewal hook now
+            // queues on aliases.lock for its own commit too, so that interleaving is
+            // excluded twice over; this lock stays because it guards the FILE,
+            // whoever the writer turns out to be.
+            //
+            // Held only when there is an anchor to rotate. A re-issue that writes no
+            // anchor has nothing for a rollback to strand, and taking the lock anyway
+            // would give it a way to fail that it does not have today.
+            if (installed && out.caPublicKey)
+                withKnownHostsLock(commitAll);
+            else
+                commitAll();
+        });
+    }
+    finally {
+        out.staged.discard();
+    }
+    if (opts.json)
+        return printJson({ alias, host: out.host, username: out.username, expiresAt: out.expiresAt, configured: installed });
+    for (const line of sshAdvice({
+        alias, host: out.host, username: out.username, expiresAt: out.expiresAt, serviceName: svc.name,
+        configured: installed, identityFile: instaKeyPath(), certificateFile: instaCertPath(alias),
+    }))
+        emit(line);
+}
+/** What to tell the user once the certificate is in hand.
+ *
+ *  Split out from computeSSH because the choice is the whole point and the
+ *  orchestration around it is network glue (untested here, as in
+ *  computeStart/computeExec/computeVolume). The rule: only advertise the alias
+ *  when the alias was actually INSTALLED. Without --setup nothing was written
+ *  to ssh_config, so `ssh api.insta` does not resolve -- printing it anyway is
+ *  advice that fails on first use and reads as a broken feature rather than a
+ *  skipped step.
+ */
+export function sshAdvice(r) {
+    const head = r.configured
+        ? [`ssh ${r.alias}  →  ${r.username}@${r.host}`]
+        : [
+            // Every option here is load-bearing. The key lives at
+            // ~/.insta/ssh/id_ed25519 and the certificate at <alias>-cert.pub;
+            // NEITHER is a path OpenSSH looks in by default, so a bare
+            // `ssh user@host` offers the user's own keys and not the credential
+            // this command just issued -- it fails, having printed success.
+            // IdentitiesOnly stops a loaded agent from spending the server's
+            // MaxAuthTries on unrelated keys before ours is ever tried.
+            `ssh -i ${shQuote(r.identityFile)} -o CertificateFile=${shQuote(r.certificateFile)} -o IdentitiesOnly=yes ${shQuote(`${r.username}@${r.host}`)}`,
+            `  run \`insta compute ssh ${r.serviceName} --setup\` once for the shorter \`ssh ${r.alias}\`, automatic renewal, and scp/-L support`,
+        ];
+    return [...head, `  certificate valid until ${r.expiresAt}`];
+}
+/** POSIX single-quoting, for a command line we PRINT for a human to paste.
+ *  A home directory with a space in it is the ordinary case this exists for. */
+function shQuote(v) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`;
+}
+/** `ssh.us-west-1.compute.example` -> `ssh.*.compute.example`.
+ *
+ *  Widening the REGION label is the whole point: one anchor then covers every
+ *  region without a line per gateway. But widening is only safe while the
+ *  wildcard stays deep inside a domain the gateway occupies, and blindly
+ *  replacing the second label does not guarantee that. `ssh.example.com` --
+ *  a hostname isSafeSSHHost accepts -- became `ssh.*.com`, which makes the
+ *  platform's CA authoritative for ssh.vendor.com and every other
+ *  `ssh.<anything>.com`.
+ *
+ *  So the wildcard is introduced ONLY when at least two fixed labels remain
+ *  after it. Anything else anchors the EXACT host: strictly narrower, always
+ *  correct, and it costs nothing but one extra known_hosts line per region for
+ *  a deployment whose names are shaped that way. Narrower-and-works beats
+ *  wider-and-guesses. */
+export function hostPatternFor(host, suffixes) {
+    // Counting labels is not enough to know where the registrable domain ends:
+    // `ssh.*.co.uk` keeps two labels after the wildcard and still ranges over
+    // every co.uk registrant. Only a suffix we KNOW we own may be widened;
+    // everything else is anchored exactly.
+    if (!mayWidenCAHost(host, suffixes))
+        return host;
+    const parts = host.split('.');
+    return [parts[0], '*', ...parts.slice(2)].join('.');
+}
 //# sourceMappingURL=compute.js.map