sliftutils 1.7.125 → 1.7.126

package/security/authorizedKeys/daemon/git.ts

@@ -0,0 +1,119 @@
+import fs from "fs/promises";
+import path from "path";
+import { spawnPromise } from "../../helpers/spawn";
+import { sourceKeyPath, sourceRepoPath } from "../sources";
+import { GIT_TIMEOUT, MAX_ERROR_BODY_LENGTH } from "./paths";
+import { sourceState } from "./state";
+
+async function pathExists(filePath: string) {
+    try {
+        await fs.access(filePath);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+/** core.sshCommand keeps the key selection with the command instead of in the environment. */
+export async function runGit(config: { args: string[]; cwd?: string; keyPath: string; allowFailure?: boolean }) {
+    let { args, cwd, keyPath, allowFailure } = config;
+    let sshCommand = `ssh -i ${keyPath} -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=accept-new`;
+    let result = await spawnPromise({
+        command: "git",
+        args: ["-c", `core.sshCommand=${sshCommand}`, ...args],
+        cwd,
+        timeoutTime: GIT_TIMEOUT,
+    });
+    if (result.error) {
+        throw new Error(`Expected git ${args.join(" ")} to run, failed with ${result.error.message}`);
+    }
+    if (result.status !== 0 && !allowFailure) {
+        throw new Error(
+            `Expected git ${args.join(" ")} to exit 0, was ${result.status}. `
+            + `${(result.stdout + result.stderr).trim().slice(0, MAX_ERROR_BODY_LENGTH)}`
+        );
+    }
+    return result;
+}
+
+export async function repoIsUsable(config: { repoPath: string; keyPath: string }) {
+    let { repoPath, keyPath } = config;
+    if (!await pathExists(path.join(repoPath, ".git"))) {
+        return false;
+    }
+    let result = await runGit({ args: ["rev-parse", "--git-dir"], cwd: repoPath, keyPath, allowFailure: true });
+    if (result.status !== 0) {
+        console.log(`Repo at ${repoPath} is not usable. ${(result.stdout + result.stderr).trim()}`);
+        return false;
+    }
+    return true;
+}
+
+/** Cloned beside the old checkout and swapped in, so a clone that fails leaves the copy we are
+    already using untouched rather than deleting the only keys we have. */
+export async function cloneRepo(config: { repoURL: string; repoPath: string; keyPath: string }) {
+    let { repoURL, repoPath, keyPath } = config;
+    let incomingPath = `${repoPath}.incoming`;
+    await fs.rm(incomingPath, { recursive: true, force: true });
+    await fs.mkdir(path.dirname(repoPath), { recursive: true });
+    await runGit({ args: ["clone", repoURL, incomingPath], keyPath });
+    await fs.rm(repoPath, { recursive: true, force: true });
+    await fs.rename(incomingPath, repoPath);
+    console.log(`Cloned ${repoURL} into ${repoPath}`);
+}
+
+export async function currentBranch(config: { repoPath: string; keyPath: string }) {
+    return (await runGit({ args: ["rev-parse", "--abbrev-ref", "HEAD"], ...config })).stdout.trim();
+}
+
+async function ensureSourceRepo(repoURL: string) {
+    let repoPath = sourceRepoPath(repoURL);
+    let keyPath = sourceKeyPath(repoURL);
+    if (!await repoIsUsable({ repoPath, keyPath })) {
+        await cloneRepo({ repoURL, repoPath, keyPath });
+    }
+    if (!sourceState(repoURL).branch) {
+        sourceState(repoURL).branch = await currentBranch({ repoPath, keyPath });
+    }
+}
+
+/** Returns what changed, so the caller can report it. A rewritten history is called out
+    separately - it means the remote no longer contains the commits we already had. */
+export async function syncRepo(repoURL: string) {
+    await ensureSourceRepo(repoURL);
+    let repoPath = sourceRepoPath(repoURL);
+    let keyPath = sourceKeyPath(repoURL);
+    let branch = sourceState(repoURL).branch;
+    let localSha = (await runGit({ args: ["rev-parse", "HEAD"], cwd: repoPath, keyPath })).stdout.trim();
+
+    // A ref listing is a few hundred bytes and no objects, so the usual case of nothing having
+    // changed costs almost nothing and we only fetch when there is something to fetch.
+    let listing = (await runGit({ args: ["ls-remote", "origin", branch], cwd: repoPath, keyPath })).stdout;
+    let remoteSha = (listing.split(/\s+/)[0] || "").trim();
+    if (!remoteSha) {
+        throw new Error(`Expected origin to report a sha for ${branch}, listed ${listing.slice(0, MAX_ERROR_BODY_LENGTH)}`);
+    }
+    if (remoteSha === localSha && remoteSha === sourceState(repoURL).lastSha) {
+        return { changed: false, historyRewritten: false, remoteSha, previousSha: localSha };
+    }
+
+    await runGit({ args: ["fetch", "--prune", "origin", branch], cwd: repoPath, keyPath });
+    remoteSha = (await runGit({ args: ["rev-parse", `origin/${branch}`], cwd: repoPath, keyPath })).stdout.trim();
+
+    let previousSha = sourceState(repoURL).lastSha || localSha;
+    let historyRewritten = false;
+    if (previousSha && previousSha !== remoteSha) {
+        // If what we already had is no longer an ancestor of the remote tip, commits were removed
+        // or rewritten rather than added.
+        let ancestry = await runGit({
+            args: ["merge-base", "--is-ancestor", previousSha, remoteSha],
+            cwd: repoPath,
+            keyPath,
+            allowFailure: true,
+        });
+        historyRewritten = ancestry.status !== 0;
+    }
+    await runGit({ args: ["reset", "--hard", `origin/${branch}`], cwd: repoPath, keyPath });
+    await runGit({ args: ["clean", "-fdx"], cwd: repoPath, keyPath });
+    return { changed: true, historyRewritten, remoteSha, previousSha };
+}

package/security/authorizedKeys/daemon/notify.ts

@@ -0,0 +1,25 @@
+import os from "os";
+import { sendDiscordNotification } from "../../notifications/discord";
+
+let hostLabelValue = "";
+
+export function setHostLabel(value: string) {
+    hostLabelValue = value;
+}
+
+// DO NOT add new calls to this. Every message goes to a real Discord server someone reads, so a
+// notification is only ever added when the user explicitly asks for that specific case. Startup,
+// success, errors, retries and recoveries all belong in console.log instead. The complete list of
+// cases that are allowed to notify is at the top of daemon.ts.
+export async function notify(message: string) {
+    let full = `**portsecure [${hostLabelValue || os.hostname()}]**: ${message}`;
+    // Logged before it is sent, and whether or not it arrives, so the journal is a complete record
+    // of what this machine had to say even when Discord is unreachable or the webhook is wrong.
+    console.log(`Discord: ${full}`);
+    try {
+        await sendDiscordNotification(full);
+    } catch (e) {
+        // A failed notification must never take the daemon down, the local log is the fallback.
+        console.log(`Failed to send the Discord notification above. ${e}`);
+    }
+}

package/security/authorizedKeys/daemon/paths.ts

@@ -0,0 +1,26 @@
+// Locations the daemon owns. Fixed rather than configurable, so every machine looks the same and
+// the config file only carries what genuinely differs between them.
+
+export const CONFIG_PATH = "/etc/portsecure/daemon.json";
+export const STATE_PATH = "/var/lib/portsecure/state.json";
+export const KEYS_HISTORY_PATH = "/var/lib/portsecure/authorized-keys-history";
+export const ROOT_AUTHORIZED_KEYS = "/root/.ssh/authorized_keys";
+export const SSHD_CONFIG_PATH = "/etc/ssh/sshd_config";
+export const SSHD_DROPIN_DIR = "/etc/ssh/sshd_config.d";
+export const SSHD_DROPIN_PATH = "/etc/ssh/sshd_config.d/00-portsecure.conf";
+export const PASSWD_PATH = "/etc/passwd";
+export const AUTH_LOG_PATH = "/var/log/auth.log";
+
+export const CHECK_INTERVAL = 60 * 1000;
+export const WEBHOOK_CHECK_INTERVAL = 5 * 60 * 1000;
+export const GIT_TIMEOUT = 120 * 1000;
+export const MAX_ERROR_BODY_LENGTH = 500;
+// A source that starts being signed by someone new is held at arm's length for this long, so a
+// stolen signing key cannot push keys onto a machine before anyone notices the warning.
+export const SIGNER_CHANGE_DELAY = 24 * 60 * 60 * 1000;
+// An unrevoke waits this long before taking effect, so a compromised signing key cannot instantly
+// undo the revocation that locked it out.
+export const UNREVOKE_DELAY = 60 * 60 * 1000;
+// After this many consecutive failures a repo is thrown away and cloned from scratch, which
+// recovers from corruption and interrupted fetches. Counted in checks, so about a quarter hour.
+export const MAX_REPO_FAILURES_BEFORE_RECLONE = 15;

package/security/authorizedKeys/daemon/portsecure.service

@@ -1,12 +1,13 @@
 [Unit]
 Description=portsecure authorized keys daemon
-Documentation=https://github.com/sliftist/portsecure
+Documentation=https://github.com/sliftist/sliftutils
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=/usr/bin/env node /opt/portsecure/portsecure-daemon.js
+ExecStart=/usr/bin/env node /opt/portsecure/sliftutils/bin/portsecuredaemon.js
+WorkingDirectory=/opt/portsecure/sliftutils
 User=root
 # Availability is the point of this daemon, so it always comes back.
 Restart=always

package/security/authorizedKeys/daemon/revocation.ts

@@ -0,0 +1,306 @@
+import fs from "fs/promises";
+import path from "path";
+import { keyFingerprint, summarizeKey } from "../authorizedKeys";
+import { deriveRevokeKey, revokeKeyPath, revokeRepoPath, revokeRepoURL } from "../revokeSource";
+import { sourceKeyPath, sourceRepoPath } from "../sources";
+import { cloneRepo, repoIsUsable, runGit } from "./git";
+import { UNREVOKE_DELAY } from "./paths";
+import { notify } from "./notify";
+import { getState, saveState } from "./state";
+
+// One revocation per key, ever. Naming the file after the fingerprint is what makes that true:
+// a second attempt from a different address lands on a name that already exists.
+const REVOCATIONS_DIR = "revocations";
+const UNREVOKES_DIR = "unrevoked";
+
+export type Attempt = {
+    ip: string;
+    user: string;
+    port: string;
+    required: string;
+    line: string;
+};
+
+export function revocationIdOf(fingerprint: string) {
+    return fingerprint.replace(/^SHA256:/, "").replace(/[^A-Za-z0-9]+/g, "-");
+}
+
+async function pathExists(filePath: string) {
+    try {
+        await fs.access(filePath);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+/** The revoke repo's key is worked out from the source's, so nothing extra had to be uploaded and
+    nothing extra is stored anywhere it could be taken from. */
+async function ensureRevokeKey(sourceURL: string) {
+    let keyPath = revokeKeyPath(sourceURL);
+    if (await pathExists(keyPath)) {
+        return keyPath;
+    }
+    let derived = deriveRevokeKey(await fs.readFile(sourceKeyPath(sourceURL), "utf8"));
+    await fs.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 });
+    await fs.writeFile(keyPath, derived.privateKeyFile, { mode: 0o600 });
+    console.log(`Derived the revoke key for ${sourceURL}`);
+    return keyPath;
+}
+
+/** Brings the revoke checkout up to date. Returns false when it cannot be reached, so a missing
+    revoke repo degrades to "keep what we already know" rather than stopping everything. */
+export async function syncRevokeRepo(sourceURL: string) {
+    let repoURL = revokeRepoURL(sourceURL);
+    let repoPath = revokeRepoPath(sourceURL);
+    let keyPath = await ensureRevokeKey(sourceURL);
+    try {
+        if (!await repoIsUsable({ repoPath, keyPath })) {
+            await cloneRepo({ repoURL, repoPath, keyPath });
+            return true;
+        }
+        let localHead = await runGit({ args: ["rev-parse", "HEAD"], cwd: repoPath, keyPath, allowFailure: true });
+        if (localHead.status !== 0) {
+            // A revoke repo with no commits yet. Nothing has ever been revoked, which is the state
+            // every one of these starts in, so there is nothing to pull and nothing to say.
+            return true;
+        }
+        let head = (await runGit({ args: ["rev-parse", "--abbrev-ref", "HEAD"], cwd: repoPath, keyPath })).stdout.trim();
+        let localSha = localHead.stdout.trim();
+        // A ref listing is a few hundred bytes and no objects, so the usual case of nothing having
+        // been revoked anywhere costs almost nothing.
+        let listing = (await runGit({ args: ["ls-remote", "origin", head], cwd: repoPath, keyPath })).stdout;
+        let remoteSha = (listing.split(/\s+/)[0] || "").trim();
+        if (remoteSha && remoteSha === localSha) {
+            return true;
+        }
+        await runGit({ args: ["fetch", "--prune", "origin"], cwd: repoPath, keyPath });
+        await runGit({ args: ["reset", "--hard", `origin/${head}`], cwd: repoPath, keyPath });
+        await runGit({ args: ["clean", "-fdx"], cwd: repoPath, keyPath });
+        return true;
+    } catch (e) {
+        console.log(`Could not sync ${repoURL}. ${e}`);
+        return false;
+    }
+}
+
+export async function readRevocationFiles(sourceURL: string) {
+    let directory = path.join(revokeRepoPath(sourceURL), REVOCATIONS_DIR);
+    if (!await pathExists(directory)) {
+        return [];
+    }
+    let revocations: { fingerprint: string; revocationId: string }[] = [];
+    for (let name of (await fs.readdir(directory)).sort()) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        try {
+            let parsed = JSON.parse(await fs.readFile(path.join(directory, name), "utf8"));
+            if (parsed.fingerprint) {
+                revocations.push({ fingerprint: parsed.fingerprint, revocationId: parsed.revocationId || name.replace(/\.json$/, "") });
+            }
+        } catch (e) {
+            console.log(`Ignoring unreadable revocation ${name}. ${e}`);
+        }
+    }
+    return revocations;
+}
+
+/** Unrevokes live in the source repo, so they are covered by its signature. */
+export async function readUnrevokeIds(sourceURL: string) {
+    let directory = path.join(sourceRepoPath(sourceURL), UNREVOKES_DIR);
+    if (!await pathExists(directory)) {
+        return new Map<string, string>();
+    }
+    let ids = new Map<string, string>();
+    for (let name of (await fs.readdir(directory)).sort()) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        try {
+            let parsed = JSON.parse(await fs.readFile(path.join(directory, name), "utf8"));
+            for (let revocationId of parsed.revocationIds || []) {
+                ids.set(revocationId, name.replace(/\.json$/, ""));
+            }
+        } catch (e) {
+            console.log(`Ignoring unreadable unrevoke ${name}. ${e}`);
+        }
+    }
+    return ids;
+}
+
+/** Writes a revocation, unless this key is already revoked. Checked twice: against what this
+    machine already knows, which needs no network, and again against the repo after pulling it,
+    so a flood of unknown keys cannot turn into a flood of commits. */
+export async function recordRevocation(config: {
+    sourceURL: string;
+    fingerprint: string;
+    keyLine: string;
+    attempt: Attempt;
+    hostLabel: string;
+}) {
+    let { sourceURL, fingerprint, keyLine, attempt, hostLabel } = config;
+    let state = getState();
+    if (state.revocations[fingerprint]) {
+        return false;
+    }
+    if (!await syncRevokeRepo(sourceURL)) {
+        console.log(`Cannot record the revocation of ${fingerprint}, ${revokeRepoURL(sourceURL)} is unreachable`);
+        return false;
+    }
+    let revocationId = revocationIdOf(fingerprint);
+    let alreadyThere = (await readRevocationFiles(sourceURL)).some(entry => entry.fingerprint === fingerprint);
+    if (alreadyThere) {
+        // Another machine got there first, which is the normal outcome when several see the same
+        // attempt. Record it locally so we never look again.
+        state.revocations[fingerprint] = {
+            fingerprint, revocationId, unrevokeSeenAt: 0, unrevokeId: "", unrevoked: false,
+            reportedRemoved: false,
+        };
+        await saveState();
+        return false;
+    }
+
+    let repoPath = revokeRepoPath(sourceURL);
+    let keyPath = revokeKeyPath(sourceURL);
+    let directory = path.join(repoPath, REVOCATIONS_DIR);
+    await fs.mkdir(directory, { recursive: true });
+    await fs.writeFile(path.join(directory, `${revocationId}.json`), JSON.stringify({
+        revocationId,
+        fingerprint,
+        key: keyLine,
+        revokedAt: new Date().toISOString(),
+        revokedBy: hostLabel,
+        reason: "used from an address its from= restriction does not allow",
+        attempt,
+    }, undefined, 4) + "\n");
+
+    await runGit({ args: ["add", "-A"], cwd: repoPath, keyPath });
+    await runGit({ args: ["-c", "user.email=portsecure@localhost", "-c", "user.name=portsecure", "commit", "-m", `revoke ${revocationId}`], cwd: repoPath, keyPath });
+    let push = await runGit({ args: ["push", "origin", "HEAD"], cwd: repoPath, keyPath, allowFailure: true });
+    if (push.status !== 0) {
+        // Most likely another machine pushed the same revocation first. The next check will pull
+        // it and record it, so there is nothing to retry here.
+        console.log(`Could not push the revocation of ${fingerprint}, will pick it up on the next check. ${(push.stdout + push.stderr).trim()}`);
+        return false;
+    }
+    state.revocations[fingerprint] = {
+        fingerprint, revocationId, unrevokeSeenAt: 0, unrevokeId: "", unrevoked: false,
+        reportedRemoved: false,
+    };
+    await saveState();
+    await notify(
+        `revoked \`${keyLine && summarizeKey(keyLine) || fingerprint}\` (\`${fingerprint}\`) after it was`
+        + ` used from \`${attempt.ip}\`, which its from= restriction does not allow (user`
+        + ` \`${attempt.user}\`, allowed \`${attempt.required}\`). Every machine will stop accepting it.`
+        + `\n\nIf this really was an attack, IMMEDIATELY remove that key from \`${sourceURL}\`.`
+        + `\nIf it was legitimate use, run this in \`${sourceURL}\` and deploy it as normal:`
+        + `\n\`\`\`\nyarn unrevoke\nyarn signfiles git\n\`\`\``
+    );
+    return true;
+}
+
+/** Takes everything the revoke repos list into local state. Once here a revocation never leaves,
+    even if the file is deleted: the key that writes revocations is on every server, so an attacker
+    holding it could otherwise erase the record that locked them out. */
+export async function absorbRevocations(sourceURLs: string[]) {
+    let state = getState();
+    let changed = false;
+    for (let sourceURL of sourceURLs) {
+        for (let entry of await readRevocationFiles(sourceURL)) {
+            if (state.revocations[entry.fingerprint]) {
+                continue;
+            }
+            state.revocations[entry.fingerprint] = {
+                fingerprint: entry.fingerprint,
+                revocationId: entry.revocationId,
+                unrevokeSeenAt: 0,
+                unrevokeId: "",
+                unrevoked: false,
+                reportedRemoved: false,
+            };
+            changed = true;
+        }
+    }
+    if (changed) {
+        await saveState();
+    }
+}
+
+/** An unrevoke is held for an hour before it counts, so a signing key that was itself compromised
+    cannot instantly undo the revocation that shut it out. */
+export async function applyUnrevokes(sourceURLs: string[]) {
+    let state = getState();
+    let unrevokeIds = new Map<string, string>();
+    for (let sourceURL of sourceURLs) {
+        for (let [revocationId, unrevokeId] of await readUnrevokeIds(sourceURL)) {
+            unrevokeIds.set(revocationId, unrevokeId);
+        }
+    }
+    for (let revocation of Object.values(state.revocations)) {
+        if (revocation.unrevoked) {
+            continue;
+        }
+        let unrevokeId = unrevokeIds.get(revocation.revocationId);
+        if (!unrevokeId) {
+            continue;
+        }
+        if (!revocation.unrevokeSeenAt) {
+            revocation.unrevokeSeenAt = Date.now();
+            revocation.unrevokeId = unrevokeId;
+            await saveState();
+            await notify(
+                `an unrevoke for \`${revocation.fingerprint}\` was published as \`${unrevokeId}\`.`
+                + ` It will be applied in ${Math.round(UNREVOKE_DELAY / 60000)} minutes, not now.`
+            );
+            continue;
+        }
+        if (Date.now() - revocation.unrevokeSeenAt < UNREVOKE_DELAY) {
+            continue;
+        }
+        revocation.unrevoked = true;
+        revocation.reportedRemoved = false;
+        await saveState();
+        await notify(
+            `the unrevoke of \`${revocation.fingerprint}\` has been applied. The key is accepted again`
+            + ` if it is still in a keys repo.`
+        );
+    }
+}
+
+export function revokedFingerprints() {
+    return new Set(
+        Object.values(getState().revocations)
+            .filter(revocation => !revocation.unrevoked)
+            .map(revocation => revocation.fingerprint)
+    );
+}
+
+/** Drops revoked keys from the merged set, and says so the first time a key actually disappears -
+    which is the thing worth knowing, rather than the mere existence of a revocation. */
+export async function removeRevokedKeys(keys: string[]) {
+    let revoked = revokedFingerprints();
+    if (!revoked.size) {
+        return keys;
+    }
+    let state = getState();
+    let allowed: string[] = [];
+    for (let key of keys) {
+        let fingerprint = keyFingerprint(key);
+        if (!fingerprint || !revoked.has(fingerprint)) {
+            allowed.push(key);
+            continue;
+        }
+        // Said once, when the key actually goes, rather than every check for as long as it is gone.
+        let revocation = state.revocations[fingerprint];
+        if (revocation && !revocation.reportedRemoved) {
+            revocation.reportedRemoved = true;
+            await saveState();
+            await notify(
+                `\`${fingerprint}\` is revoked, so it has been removed from root's authorized_keys`
+                + ` and this machine no longer accepts it.`
+            );
+        }
+    }
+    return allowed;
+}

package/security/authorizedKeys/daemon/rootKeys.ts

@@ -0,0 +1,135 @@
+import fs from "fs/promises";
+import path from "path";
+import { keyFingerprint, keyRestriction, summarizeKey } from "../authorizedKeys";
+import { KEYS_HISTORY_PATH, ROOT_AUTHORIZED_KEYS } from "./paths";
+import { notify } from "./notify";
+
+const KEY_FILE_HEADER = "# Managed by portsecure. Manual changes are reverted and reported.";
+
+async function pathExists(filePath: string) {
+    try {
+        await fs.access(filePath);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+/** Keys are matched by the key itself, not by the text of the line, so changing which addresses a
+    key may be used from reads as that one key changing rather than as one key leaving and another
+    arriving. A line we cannot read a key out of falls back to the whole line. */
+function keyIdentity(keyLine: string) {
+    return keyFingerprint(keyLine) || keyLine;
+}
+
+export function describeKeyDifference(config: { before: string[]; after: string[] }) {
+    let { before, after } = config;
+    let beforeByKey = new Map(before.map(key => [keyIdentity(key), key]));
+    let afterByKey = new Map(after.map(key => [keyIdentity(key), key]));
+
+    let lines: string[] = [];
+    for (let [identity, keyLine] of afterByKey) {
+        if (!beforeByKey.has(identity)) {
+            lines.push(`+ added   ${summarizeKey(keyLine)}\n          from ${keyRestriction(keyLine)}`);
+        }
+    }
+    for (let [identity, keyLine] of beforeByKey) {
+        if (!afterByKey.has(identity)) {
+            lines.push(`- removed ${summarizeKey(keyLine)}\n          from ${keyRestriction(keyLine)}`);
+        }
+    }
+    for (let [identity, previousLine] of beforeByKey) {
+        let currentLine = afterByKey.get(identity);
+        if (!currentLine || currentLine === previousLine) {
+            continue;
+        }
+        let previousFrom = keyRestriction(previousLine);
+        let currentFrom = keyRestriction(currentLine);
+        if (previousFrom !== currentFrom) {
+            lines.push(
+                `~ changed ${summarizeKey(currentLine)}\n          from ${previousFrom}\n`
+                + `            to ${currentFrom}`
+            );
+            continue;
+        }
+        lines.push(
+            `~ changed ${summarizeKey(currentLine)}\n          from ${currentFrom}\n`
+            + `          its options or comment changed`
+        );
+    }
+    if (!lines.length) {
+        return "(no keys differ)";
+    }
+    return lines.join("\n");
+}
+
+export async function readAuthorizedKeysFile(filePath: string) {
+    if (!await pathExists(filePath)) {
+        return [];
+    }
+    let contents = await fs.readFile(filePath, "utf8");
+    return contents.split("\n").map(line => line.trim()).filter(line => line && !line.startsWith("#"));
+}
+
+export async function writeAuthorizedKeysFile(config: { filePath: string; keys: string[] }) {
+    let { filePath, keys } = config;
+    let directory = path.dirname(filePath);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    await fs.chmod(directory, 0o700);
+    // Written to a temporary file first, so an interrupted write can never leave root with a
+    // truncated authorized_keys and no way back in.
+    let temporaryPath = `${filePath}.portsecure-tmp`;
+    await fs.writeFile(temporaryPath, `${KEY_FILE_HEADER}\n${keys.join("\n")}\n`, { mode: 0o600 });
+    await fs.rename(temporaryPath, filePath);
+}
+
+/** Keeps a copy of whatever is about to be overwritten, named for the moment it was replaced.
+    Recovers a key that was clobbered by mistake, and doubles as the history of who had access.
+    The very first archive is the most valuable one, since it holds the keys from before portsecure
+    took the file over. */
+export async function archiveAuthorizedKeys(config: { filePath: string; reason: string }) {
+    let { filePath, reason } = config;
+    if (!await pathExists(filePath)) {
+        return "";
+    }
+    let contents = await fs.readFile(filePath, "utf8");
+    await fs.mkdir(KEYS_HISTORY_PATH, { recursive: true, mode: 0o700 });
+    await fs.chmod(KEYS_HISTORY_PATH, 0o700);
+    let stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let archivePath = path.join(KEYS_HISTORY_PATH, `${stamp}-${reason}.authorized_keys`);
+    let attempt = 1;
+    while (await pathExists(archivePath)) {
+        attempt++;
+        archivePath = path.join(KEYS_HISTORY_PATH, `${stamp}-${reason}-${attempt}.authorized_keys`);
+    }
+    await fs.writeFile(archivePath, contents, { mode: 0o600 });
+    return archivePath;
+}
+
+/** Puts the allowed keys back in place if anything else changed them. */
+export async function enforceRootKeys(config: { keys: string[]; reason: string }) {
+    let { keys, reason } = config;
+    if (!keys.length) {
+        // No sources, or none of them readable. Writing an empty file would lock everyone out, so
+        // whatever access is already in place stays exactly as it is.
+        console.log(`No keys came from any source, leaving ${ROOT_AUTHORIZED_KEYS} as it is`);
+        return;
+    }
+    let currentKeys = await readAuthorizedKeysFile(ROOT_AUTHORIZED_KEYS);
+    let matches = currentKeys.length === keys.length && currentKeys.every((key, index) => key === keys[index]);
+    if (matches) {
+        return;
+    }
+    let archivePath = await archiveAuthorizedKeys({ filePath: ROOT_AUTHORIZED_KEYS, reason });
+    await writeAuthorizedKeysFile({ filePath: ROOT_AUTHORIZED_KEYS, keys });
+    let difference = describeKeyDifference({ before: currentKeys, after: keys });
+    let archiveNote = archivePath && `\nThe previous file is kept at \`${archivePath}\`.` || "";
+    if (reason === "repo") {
+        await notify(`root's authorized_keys was updated from the keys repo.\n\`\`\`\n${difference}\n\`\`\`${archiveNote}`);
+        return;
+    }
+    await notify(
+        `root's authorized_keys was changed outside portsecure and has been reverted to the keys repo.`
+        + `\n\`\`\`\n${difference}\n\`\`\`${archiveNote}`
+    );
+}