sliftutils 1.7.128 → 1.7.129

package/security/machines/identity.ts

@@ -0,0 +1,199 @@
+import crypto from "crypto";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { generateTestCA, getMachineId, identityStorageKey, IdentityStorageType, verifyMachineIdForPublicKey } from "../../misc/https/certs";
+import { runOverSSH, writeRemoteFile } from "../helpers/remoteSSH";
+
+// A machine's identity is the CA it generated for itself, kept in one file in the home directory
+// of whoever runs it. The name carries the domain it belongs to, so a machine can hold one per
+// domain, and the id itself is a hash of that CA's public key - which is why a machine cannot
+// claim to be another one without holding its key.
+const IDENTITY_PREFIX = "keystore_";
+const IDENTITY_SUFFIX = `_${identityStorageKey}.json`;
+// How stale a signed packet may be. Long enough for clock skew between two machines, short enough
+// that a captured packet is not worth replaying.
+export const PACKET_LIFETIME = 2 * 60 * 1000;
+
+export type Identity = {
+    machineId: string;
+    domain: string;
+    fullDomain: string;
+    fileName: string;
+};
+
+function identityFileName(domain: string) {
+    return `${IDENTITY_PREFIX}${domain}${IDENTITY_SUFFIX}`;
+}
+
+/** The domain out of an identity file's name, or "" if it is not one. */
+function domainOfFileName(fileName: string) {
+    if (!fileName.startsWith(IDENTITY_PREFIX) || !fileName.endsWith(IDENTITY_SUFFIX)) {
+        return "";
+    }
+    return fileName.slice(IDENTITY_PREFIX.length, -IDENTITY_SUFFIX.length);
+}
+
+function describeIdentity(config: { domain: string; stored: IdentityStorageType }) {
+    let { domain, stored } = config;
+    return {
+        machineId: getMachineId(stored.domain, domain),
+        domain,
+        fullDomain: stored.domain,
+        fileName: identityFileName(domain),
+    };
+}
+
+/** Every domain this machine holds an identity under. A machine has one identity per domain, and
+    they are different machine ids, so which one is meant is a real question rather than a detail. */
+export async function localDomains() {
+    let domains: string[] = [];
+    for (let name of (await fs.readdir(os.homedir()).catch(() => [] as string[])).sort()) {
+        let domain = domainOfFileName(name);
+        if (domain) {
+            domains.push(domain);
+        }
+    }
+    return domains;
+}
+
+/** This machine's identity under one domain. Undefined when it has none under that one.
+
+    The domain is required everywhere it appears. A machine has a different identity, and so a
+    different machine id, under every domain it runs under, so "this machine" on its own does not
+    name anything: answering under the wrong one means answering as a machine we are not. */
+export async function localIdentity(domain: string): Promise<Identity | undefined> {
+    if (!domain) {
+        throw new Error(`Expected a domain, was ${JSON.stringify(domain)}`);
+    }
+    let contents = await fs.readFile(path.join(os.homedir(), identityFileName(domain)), "utf8").catch(() => "");
+    if (!contents) {
+        return undefined;
+    }
+    return describeIdentity({ domain, stored: JSON.parse(contents) });
+}
+
+/** This machine's identity and its keys, for signing. */
+export async function localIdentityKeys(domain: string) {
+    let identity = await localIdentity(domain);
+    if (!identity) {
+        throw new Error(
+            `Expected an identity for ${domain} at ${path.join(os.homedir(), identityFileName(domain))},`
+            + ` there is none.\n`
+            + `This machine has: ${(await localDomains()).join(", ") || "no identities at all"}`
+        );
+    }
+    let stored: IdentityStorageType = JSON.parse(
+        await fs.readFile(path.join(os.homedir(), identity.fileName), "utf8")
+    );
+    return { identity, stored };
+}
+
+/** The identity of another machine under one domain, over ssh. Undefined when it has none under
+    that domain, whatever else it may have under others. */
+export async function remoteIdentity(host: string, domain: string): Promise<Identity | undefined> {
+    if (!domain) {
+        throw new Error(`Expected a domain, was ${JSON.stringify(domain)}`);
+    }
+    let home = (await runOverSSH({ host, script: `echo $HOME` })).stdout.trim();
+    if (!home) {
+        throw new Error(`Expected ${host} to report a home directory, it reported nothing`);
+    }
+    let contents = await runOverSSH({
+        host,
+        script: `cat ${home}/${identityFileName(domain)} 2>/dev/null || true`,
+    });
+    if (!contents.stdout.trim()) {
+        return undefined;
+    }
+    return describeIdentity({ domain, stored: JSON.parse(contents.stdout) });
+}
+
+/** Gives a machine an identity it does not have yet, by generating one here and writing it there.
+
+    The CA is self signed and never leaves that machine afterwards, so generating it here is only a
+    convenience: what matters is that the private key ends up in one place and the id is the hash
+    of its public half. */
+export async function createRemoteIdentity(config: { host: string; domain: string }) {
+    let { host, domain } = config;
+    let generated = generateTestCA(domain);
+    let stored: IdentityStorageType = {
+        domain: generated.domain,
+        certB64: generated.cert.toString("base64"),
+        keyB64: generated.key.toString("base64"),
+    };
+    let home = (await runOverSSH({ host, script: `echo $HOME` })).stdout.trim();
+    await writeRemoteFile({
+        host,
+        filePath: `${home}/${identityFileName(domain)}`,
+        contents: JSON.stringify(stored),
+        fileMode: "600",
+        // The home directory is already there, this is only what it is created with if it is not.
+        directoryMode: "700",
+    });
+    return describeIdentity({ domain, stored });
+}
+
+/** The raw ed25519 public key out of a certificate, which is what the machine id is a hash of. */
+function publicKeyBytes(certPEM: string) {
+    let spki = new crypto.X509Certificate(certPEM).publicKey.export({ type: "spki", format: "der" });
+    // An ed25519 SPKI is a fixed 12 byte header followed by the 32 byte key.
+    return spki.subarray(spki.length - 32);
+}
+
+export type TrustPacket = {
+    machineId: string;
+    certB64: string;
+    signedAt: number;
+    signatureB64: string;
+};
+
+/** Proves we hold the private key behind our machine id, right now. The signature covers the id
+    and the time, so the packet cannot be replayed later or reused for another id. */
+export async function signTrustPacket(domain: string): Promise<TrustPacket> {
+    let { identity, stored } = await localIdentityKeys(domain);
+    let signedAt = Date.now();
+    let signature = crypto.sign(
+        null,
+        Buffer.from(`${identity.machineId} ${signedAt}`),
+        crypto.createPrivateKey(Buffer.from(stored.keyB64, "base64").toString())
+    );
+    return {
+        machineId: identity.machineId,
+        certB64: stored.certB64,
+        signedAt,
+        signatureB64: signature.toString("base64"),
+    };
+}
+
+/** Whether a packet really came from the machine it names. Says why when it did not, because
+    "this is not that machine" and "this arrived too late" are different problems. */
+export function verifyTrustPacket(packet: TrustPacket) {
+    if (!packet || !packet.machineId || !packet.certB64 || !packet.signatureB64) {
+        return { valid: false, problem: "the packet is missing fields" };
+    }
+    if (Math.abs(Date.now() - packet.signedAt) > PACKET_LIFETIME) {
+        return { valid: false, problem: `it was signed ${Math.round((Date.now() - packet.signedAt) / 1000)}s ago` };
+    }
+    let certPEM = Buffer.from(packet.certB64, "base64").toString();
+    let publicKey: crypto.KeyObject;
+    try {
+        publicKey = new crypto.X509Certificate(certPEM).publicKey;
+    } catch (e) {
+        return { valid: false, problem: `its certificate could not be read, ${e}` };
+    }
+    // The id is a hash of the public key, so this is what stops a machine claiming another's id.
+    if (!verifyMachineIdForPublicKey({ machineId: packet.machineId, publicKey: publicKeyBytes(certPEM) })) {
+        return { valid: false, problem: "the machine id does not belong to that certificate" };
+    }
+    let signed = crypto.verify(
+        null,
+        Buffer.from(`${packet.machineId} ${packet.signedAt}`),
+        publicKey,
+        Buffer.from(packet.signatureB64, "base64")
+    );
+    if (!signed) {
+        return { valid: false, problem: "the signature does not check out" };
+    }
+    return { valid: true, problem: "" };
+}

package/security/machines/machines.ts

@@ -0,0 +1,355 @@
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { CONFIG_PATH } from "../authorizedKeys/daemon/paths";
+import { revokeRepo, syncRepoFiles } from "../authorizedKeys/daemon/repoFiles";
+import { listRepoDir, readRepoFile } from "../authorizedKeys/daemon/repoFiles";
+import { newRevocationId, pairKey, readRevocationFiles, readUnrevokes } from "../authorizedKeys/daemon/revocation";
+import { runGit } from "../authorizedKeys/daemon/git";
+import { ensureRevokeKey } from "../authorizedKeys/daemon/repoFiles";
+import { verifyCheckout } from "../authorizedKeys/daemon/trust";
+import { revokeRepoPath, revokeRepoURL } from "../authorizedKeys/revokeSource";
+import { sourceRepoPath } from "../authorizedKeys/sources";
+import { notify } from "../authorizedKeys/daemon/notify";
+import { areDiscordNotificationsConfigured, configureDiscordNotifications, DEFAULT_WEBHOOK_FILE_PATH } from "../notifications/discord";
+import { unrevokeInEffect } from "./trustState";
+import { spawnPromise } from "../helpers/spawn";
+
+// Which machines this system talks to, kept in the same repo as the ssh keys. That repo is already
+// signed, already distributed to every machine, and already has somewhere to record a rejection,
+// so a second one would only be a second thing to keep in step.
+export const MACHINES_DIR = "machines";
+const REVOCATIONS_DIR = "revocations";
+const REVOCATION_REASON = "a machine talked to us from an unapproved IP";
+// The revoke repo is pulled at most this often. A check happens per request, and a request must
+// not cost a round trip to github.
+const REVOKE_SYNC_INTERVAL = 60 * 1000;
+// Where a Windows machine is expected to keep the repo, relative to the working directory. There
+// is no daemon there to ask, and no /etc to look in.
+const WINDOWS_REPO_PATH = "../authorized_keys";
+
+/** One machine we are willing to talk to, and the addresses it may talk to us from. */
+export type MachineState = {
+    machineId: string;
+    ips: string[];
+    addedAt: string;
+};
+
+async function pathExists(filePath: string) {
+    try {
+        await fs.access(filePath);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+function machineFilePath(repoPath: string, machineId: string) {
+    return path.join(repoPath, MACHINES_DIR, `${machineId}.json`);
+}
+
+/** Reads every machine a checkout lists, or sets them.
+
+    Passing `machines` makes the repo match it exactly: machines named are written with the
+    addresses given, and machines not named are removed. That is why the addresses are part of
+    setting rather than a separate step - a machine with no address it may talk from is not a
+    machine we would accept anyway, so there is no state where naming one without them means
+    anything. Read first, change what you want, write the result.
+
+    Nothing here signs or commits anything. The signature is what every other machine checks before
+    believing any of this, and it takes the hardware key, so `yarn signfiles git` is still yours to
+    run afterwards. */
+export async function machineState(config: {
+    repoPath: string;
+    machines?: { machineId: string; ips: string[] }[];
+}): Promise<MachineState[]> {
+    let { repoPath, machines } = config;
+    let existing = await readMachines(repoPath);
+    if (!machines) {
+        return [...existing.values()];
+    }
+
+    let directory = path.join(repoPath, MACHINES_DIR);
+    let written: MachineState[] = [];
+    for (let machine of machines) {
+        if (!machine.machineId) {
+            throw new Error(`Expected a machineId, was ${JSON.stringify(machine.machineId)}`);
+        }
+        if (!machine.ips.length) {
+            throw new Error(
+                `Expected addresses for ${machine.machineId}, was none. A machine is trusted from`
+                + ` the addresses it may talk from, so leave it out of the list to remove it.`
+            );
+        }
+        let ips = machine.ips.filter((ip, index) => ip && machine.ips.indexOf(ip) === index);
+        let state: MachineState = {
+            machineId: machine.machineId,
+            // In the order given, without duplicates, so the file reads the way it was set.
+            ips,
+            addedAt: existing.get(machine.machineId)?.addedAt || new Date().toISOString(),
+        };
+        await fs.mkdir(directory, { recursive: true });
+        await fs.writeFile(machineFilePath(repoPath, state.machineId), JSON.stringify(state, undefined, 4) + "\n");
+        written.push(state);
+    }
+
+    // Whatever the repo had and the caller did not name is no longer trusted.
+    for (let machineId of existing.keys()) {
+        if (!machines.some(machine => machine.machineId === machineId)) {
+            await fs.rm(machineFilePath(repoPath, machineId), { force: true });
+        }
+    }
+    return written;
+}
+
+/** Every machine the repo lists. */
+async function readMachines(repoPath: string) {
+    let machines = new Map<string, MachineState>();
+    let directory = path.join(repoPath, MACHINES_DIR);
+    let names = await fs.readdir(directory).catch(() => [] as string[]);
+    for (let name of names.sort()) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        try {
+            let parsed = JSON.parse(await fs.readFile(path.join(directory, name), "utf8"));
+            let machineId = parsed.machineId || name.replace(/\.json$/, "");
+            machines.set(machineId, { machineId, ips: parsed.ips || [], addedAt: parsed.addedAt || "" });
+        } catch (e) {
+            console.log(`Ignoring unreadable machine file ${name}. ${e}`);
+        }
+    }
+    return machines;
+}
+
+async function isKeysRepo(repoPath: string) {
+    return await pathExists(path.join(repoPath, ".git"))
+        && await pathExists(path.join(repoPath, "authorized_keys"));
+}
+
+async function originOf(repoPath: string) {
+    let origin = await spawnPromise({ command: "git", args: ["remote", "get-url", "origin"], cwd: repoPath });
+    let url = origin.stdout.trim();
+    if (origin.status !== 0 || !url) {
+        throw new Error(`Expected ${repoPath} to have an origin remote, it has none`);
+    }
+    return url;
+}
+
+/** The keys repo this machine answers from, and the one anything editing the machine list edits.
+
+    On a host, that is the checkout the daemon already keeps up to date. On Windows there is no
+    daemon and no /etc, so the repo is expected beside the working directory, which is where a
+    developer working on both would have it.
+
+    Never the directory the command happens to be run from. Which repo this machine trusts is a
+    property of the machine, not of where somebody was standing when they typed something. */
+export async function resolveKeysRepo() {
+    if (os.platform() === "win32") {
+        let repoPath = path.resolve(WINDOWS_REPO_PATH);
+        if (!await isKeysRepo(repoPath)) {
+            throw new Error(
+                `Expected ${repoPath} to be an authorized_keys repo, it is not.\n`
+                + `On Windows the repo is read from there, so clone it beside this one:\n`
+                + `  git clone <your authorized_keys repo> ${repoPath}`
+            );
+        }
+        return { repoPath, sourceURL: await originOf(repoPath) };
+    }
+
+    let config = await fs.readFile(CONFIG_PATH, "utf8").catch(() => "");
+    let sourceURL = config && (JSON.parse(config).repoSources || [])[0] || "";
+    if (!sourceURL) {
+        throw new Error(
+            `Expected this machine to be set up with an authorized_keys repo, ${CONFIG_PATH} names none.\n`
+            + `Set it up first:\n`
+            + `  yarn setupnotify <discord-webhook-url>\n`
+            + `  yarn securessh add <repo-private-key> <repo-url>`
+        );
+    }
+    let repoPath = sourceRepoPath(sourceURL);
+    if (!await isKeysRepo(repoPath)) {
+        throw new Error(
+            `Expected a checkout of ${sourceURL} at ${repoPath}, there is none.\n`
+            + `Run \`yarn securessh update\` to put it back.`
+        );
+    }
+    return { repoPath, sourceURL };
+}
+
+let lastRevokeSync = 0;
+
+/** Pulled at most once a REVOKE_SYNC_INTERVAL, because this is asked per request. A sync that
+    fails leaves the checkout we already have, which is the safe direction: revocations we know
+    about stay known. */
+async function syncRevocations(sourceURL: string) {
+    if (Date.now() - lastRevokeSync < REVOKE_SYNC_INTERVAL) {
+        return;
+    }
+    lastRevokeSync = Date.now();
+    try {
+        await syncRepoFiles(revokeRepo(sourceURL));
+    } catch (e) {
+        console.log(`Could not read ${revokeRepoURL(sourceURL)}, using the revocations already here. ${e}`);
+    }
+}
+
+/** Machine revocations, read out of the revoke repo the same way key revocations are. */
+async function readMachineRevocations(sourceURL: string) {
+    let repo = revokeRepo(sourceURL);
+    let revocations: { revocationId: string; machineId: string; ip: string }[] = [];
+    for (let name of await listRepoDir(repo, REVOCATIONS_DIR)) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        try {
+            let parsed = JSON.parse(await readRepoFile(repo, path.join(REVOCATIONS_DIR, name)) || "");
+            if (parsed.machineId) {
+                revocations.push({
+                    revocationId: parsed.revocationId || name.replace(/\.json$/, ""),
+                    machineId: parsed.machineId,
+                    ip: parsed.ip || "",
+                });
+            }
+        } catch (e) {
+            console.log(`Ignoring unreadable revocation ${name}. ${e}`);
+        }
+    }
+    return revocations;
+}
+
+/** Sends the one notification this file is allowed to send, when it can.
+
+    The daemon configures notifications on startup and would simply send. This can also run in some
+    other process, which has not, so the webhook is picked up here if it is readable. A machine
+    with no webhook set up still records the revocation - being unable to tell anyone is not a
+    reason to keep accepting a machine that is being misused. */
+async function notifyBestEffort(headline: string, body: string) {
+    try {
+        if (!areDiscordNotificationsConfigured()) {
+            // Read first: configureDiscordNotifications exits the process when the file is missing,
+            // which is right for the daemon at startup and wrong for a library call.
+            await fs.readFile(DEFAULT_WEBHOOK_FILE_PATH, "utf8");
+            await configureDiscordNotifications({ filePath: DEFAULT_WEBHOOK_FILE_PATH });
+        }
+        await notify(headline, body);
+    } catch (e) {
+        console.log(`Could not send a notification about this, it is only in the log. ${e}`);
+    }
+}
+
+/** Records that a machine we accept talked to us from an address it is not allowed from. One per
+    machine and address, so a second address is a second revocation and an unrevoke of the first
+    does not cover it. */
+async function recordMachineRevocation(config: {
+    sourceURL: string;
+    machineId: string;
+    ip: string;
+    hostLabel: string;
+}) {
+    let { sourceURL, machineId, ip, hostLabel } = config;
+    let repoPath = revokeRepoPath(sourceURL);
+    let keyPath = await ensureRevokeKey(sourceURL);
+    let revocationId = newRevocationId(machineId);
+    let directory = path.join(repoPath, REVOCATIONS_DIR);
+    await fs.mkdir(directory, { recursive: true });
+    await fs.writeFile(path.join(directory, `${revocationId}.json`), JSON.stringify({
+        revocationId,
+        machineId,
+        ip,
+        revokedAt: new Date().toISOString(),
+        revokedBy: hostLabel,
+        reason: REVOCATION_REASON,
+    }, 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) {
+        // Another machine most likely recorded the same thing first, and the next read picks it up.
+        console.log(`Could not push the revocation of ${machineId} from ${ip}. ${(push.stdout + push.stderr).trim()}`);
+        return;
+    }
+    console.log(`Revoked ${machineId} from ${ip}, ${revocationId}`);
+
+    // Said by whoever wrote the revocation, once, the same as for an ssh key. Machines that only
+    // read it later say nothing, or one event would be reported by every machine that saw it.
+    await notifyBestEffort(
+        `SUSPICIOUS IP ${ip} FROZE MACHINE ${machineId}`,
+        `A machine we trust talked to us from ${ip}, which is not an address it is allowed to talk`
+        + ` from. It proved it holds that machine's key, so either someone else has a copy of it,`
+        + ` or that machine's address changed.`
+        + `\n\nIt is frozen everywhere now, and nothing accepts it.`
+        + `\n\nIf this was an attack, remove \`machines/${machineId}.json\` from \`${sourceURL}\` now.`
+        + `\nIf it was legitimate, run \`yarn unrevoke git\` in that repo. It allows ${ip} for that`
+        + ` machine, and takes an hour to reach every machine.`
+        + `\n\nmachine: \`${machineId}\``
+        + `\nfrozen by: \`${hostLabel}\``
+    );
+}
+
+/** Whether we will talk to this machine, coming from this address.
+
+    Both halves are required and neither is a guess: the caller knows the machine id because the
+    connection proved it, and knows the address because the packets came from there. A machine we
+    do not list is simply not accepted. A machine we do list, arriving from an address it does not
+    have, is treated as the same kind of event as a stolen ssh key - it is revoked everywhere, and
+    stays revoked until an unrevoke allows that machine from that address.
+
+    Throws when the repo itself cannot be read or is not signed, rather than answering false: that
+    is a broken installation, not a rejected machine, and the two deserve different handling. */
+export async function isMachineAccepted(config: { machineId: string; ip: string }): Promise<boolean> {
+    let { machineId, ip } = config;
+    if (!machineId || !ip) {
+        throw new Error(`Expected a machineId and an ip, was ${JSON.stringify(machineId)} and ${JSON.stringify(ip)}`);
+    }
+    let { repoPath, sourceURL } = await resolveKeysRepo();
+    // Unsigned, or signed over different contents, means the machine list is not evidence of
+    // anything. Same gate the ssh keys go through.
+    await verifyCheckout(repoPath);
+
+    let machine = (await readMachines(repoPath)).get(machineId);
+    if (!machine) {
+        return false;
+    }
+
+    await syncRevocations(sourceURL);
+    let unrevokes = await readUnrevokes(sourceURL).catch(() => ({ pairs: new Map(), legacyIds: new Map() }));
+    // An unrevoke is only honoured once it has waited out its hour, exactly as an ssh key's is.
+    let allowedAgain = async (pair: string) => {
+        let unrevokeId = unrevokes.pairs.get(pair);
+        return !!unrevokeId && await unrevokeInEffect(unrevokeId);
+    };
+    let revocations = await readMachineRevocations(sourceURL);
+    // Any revocation nothing has undone keeps the machine out, from everywhere, the way a revoked
+    // ssh key is out everywhere rather than only from the address it was misused from.
+    let revoked = false;
+    for (let revocation of revocations) {
+        if (revocation.machineId !== machineId) {
+            continue;
+        }
+        if (!await allowedAgain(pairKey({ fingerprint: revocation.machineId, ip: revocation.ip }))) {
+            revoked = true;
+        }
+    }
+    if (revoked) {
+        return false;
+    }
+
+    if (machine.ips.includes(ip)) {
+        return true;
+    }
+
+    // Listed, but talking to us from somewhere it should not be. Recorded once for this machine
+    // and address, so being talked to repeatedly does not write repeatedly.
+    let pair = pairKey({ fingerprint: machineId, ip });
+    let alreadyRecorded = revocations.some(revocation =>
+        pairKey({ fingerprint: revocation.machineId, ip: revocation.ip }) === pair);
+    if (!alreadyRecorded && !await allowedAgain(pair)) {
+        await recordMachineRevocation({ sourceURL, machineId, ip, hostLabel: os.hostname() });
+    }
+    return false;
+}

package/security/machines/trustClient.ts

@@ -0,0 +1,51 @@
+import { signTrustPacket } from "./identity";
+
+// The other half of the demonstration: asks a server whether it trusts this machine. The answer
+// depends on the address this machine reaches the server from, which is why the client cannot
+// work it out alone.
+const TRUST_PATH = "/trusted";
+const USAGE = `Usage: yarn machineclient <url> <domain>
+
+Asks that server whether this machine is trusted, proving which machine it is with a signed packet.
+The server decides using the address we reach it from, so the answer is about how we are talking to
+it, not only about who we are.
+
+The domain is required: this machine has a different identity under each one, and the answer is
+about the identity we sign with.`;
+
+export type TrustAnswer = {
+    trusted: boolean;
+    machineId?: string;
+    ip?: string;
+    reason?: string;
+};
+
+/** Asks one server whether it trusts this machine, as it is under this domain. */
+export async function askIfTrusted(config: { baseURL: string; domain: string }): Promise<TrustAnswer> {
+    let { baseURL, domain } = config;
+    let packet = await signTrustPacket(domain);
+    let url = `${baseURL.replace(/\/+$/, "")}${TRUST_PATH}`;
+    let response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(packet),
+    });
+    return await response.json() as TrustAnswer;
+}
+
+export async function main() {
+    let [baseURL, domain] = process.argv.slice(2);
+    if (!baseURL || !domain) {
+        throw new Error(USAGE);
+    }
+    let answer = await askIfTrusted({ baseURL, domain });
+    console.log(`${answer.trusted && "TRUSTED" || "NOT TRUSTED"} by ${baseURL}`);
+    console.log(`  machine ${answer.machineId || "(not established)"}`);
+    console.log(`  seen coming from ${answer.ip || "(unknown)"}`);
+    if (answer.reason) {
+        console.log(`  ${answer.reason}`);
+    }
+    if (!answer.trusted) {
+        process.exitCode = 1;
+    }
+}