@counterfact-labs/cli 0.1.3 → 0.2.4

package/dist/gatekeeper/model.js

@@ -0,0 +1,70 @@
+import { createHash, randomUUID } from "node:crypto";
+import { executionRequest } from "../analysis-core/contracts/requests.js";
+export class ModelConfigurationError extends Error {
+    name = "ModelConfigurationError";
+}
+export function relayModel(options) {
+    const { client, bundleVersion, reservationId, reservationToken, onUsage } = options;
+    if (!bundleVersion.trim() || !reservationId.trim() || !reservationToken?.trim() || reservationToken.length > 256)
+        throw new ModelConfigurationError("Invalid relay configuration");
+    const identities = new Map();
+    const originals = new WeakMap();
+    let callCount = 0;
+    function view(retry) {
+        return {
+            settleStartedOnError: true,
+            withRetry: view,
+            async execute(request, execution = {}) {
+                options.signal?.throwIfAborted();
+                execution.signal?.throwIfAborted();
+                let snapshot;
+                let inputBytes;
+                try {
+                    // Match JSON transport semantics, including omitted optional data fields.
+                    snapshot = executionRequest.parse(JSON.parse(JSON.stringify(request)));
+                    inputBytes = Buffer.byteLength(JSON.stringify(snapshot.inputs));
+                }
+                catch {
+                    throw new Error("Invalid relay request data");
+                }
+                execution.onSend?.(inputBytes);
+                const key = createHash("sha256").update(JSON.stringify(snapshot)).digest("hex");
+                const matching = identities.get(key);
+                let identity;
+                if (retry > 0) {
+                    const original = originals.get(request);
+                    const candidates = original ? [...original].filter(id => matching?.has(id)) : [...matching ?? []];
+                    if (candidates.length !== 1)
+                        throw new Error("Ambiguous relay call identity");
+                    identity = candidates[0];
+                }
+                else {
+                    if (callCount >= 4096)
+                        throw new Error("Relay call limit reached");
+                    identity = randomUUID();
+                    callCount++;
+                    identities.set(key, new Set([...matching ?? [], identity]));
+                    originals.set(request, new Set([...originals.get(request) ?? [], identity]));
+                }
+                let reply;
+                try {
+                    const signals = [options.signal, execution.signal].filter((signal) => !!signal);
+                    reply = await client.call({ ...snapshot, bundleVersion, reservationId, reservationToken, callId: identity }, { signal: signals.length ? AbortSignal.any(signals) : undefined });
+                }
+                catch {
+                    throw new Error("Relay request could not finish");
+                }
+                if (!reply.ok)
+                    throw new Error(`Relay refused the request: ${reply.code}`);
+                try {
+                    onUsage?.({ ...reply.usage, template: snapshot.template, model: snapshot.model });
+                }
+                catch {
+                    // A failed counter must not discard an answer or expose the sink's error text.
+                }
+                return reply.answer;
+            },
+        };
+    }
+    return view(0);
+}

package/dist/gatekeeper/production-attestation.js

@@ -0,0 +1,149 @@
+import { constants, verify, X509Certificate } from "node:crypto";
+import { z } from "zod";
+import { GOOGLE_ATTESTATION_ISSUER, MAX_ATTESTATION_BYTES, PRODUCTION_EVIDENCE_VERSION, RELAY_CHANNEL_AUDIENCE, attestationChallenge, evidenceBinding, googleAttestationClaims, observedAttestationClaims, productionEvidence } from "../contract/messages.js";
+import { decodeBase64url } from "../transport/base64url.js";
+import { isApprovedHardware } from "./trust/hardware.js";
+import { AttestationError } from "./attestation.js";
+import { validateCertificatePath } from "./certificate-path.js";
+import { validateProductionTrust, validateWorkloadPolicy } from "./trust/policy.js";
+/** A published client needs every trust constraint configured before it can connect to production. */
+export function assertProductionTrustConfigured(value) {
+    try {
+        validateProductionTrust(value);
+    }
+    catch {
+        throw new Error("Production trust is not configured for a CLI release.");
+    }
+}
+const ISSUER_CLOCK_SKEW_SECONDS = 60;
+const headerSchema = z.object({
+    alg: z.literal("RS256"), typ: z.literal("JWT").optional(), kid: z.string().max(256).optional(),
+    x5c: z.array(z.string().min(1).max(8192)).min(1).max(5),
+}).strict();
+/** Both peers supply bytes from their actual TLS socket; the transport owns freshness and socket reuse. */
+export function channelEvidenceBinding(binding) {
+    try {
+        attestationChallenge.parse({ version: PRODUCTION_EVIDENCE_VERSION, challenge: binding.challenge });
+        if (!(binding.exportedKeyMaterial instanceof Uint8Array) || binding.exportedKeyMaterial.byteLength !== 32)
+            throw new Error();
+        return { audience: RELAY_CHANNEL_AUDIENCE,
+            nonces: [Buffer.from(binding.exportedKeyMaterial).toString("base64url"), binding.challenge] };
+    }
+    catch {
+        throw new AttestationError("Invalid production attestation channel binding");
+    }
+}
+/** The caller's binding comes from the channel/health/action owner, never from the token being verified. */
+export async function verifyProductionEvidence(token, binding, trust, now = Math.floor(Date.now() / 1000)) {
+    let validated;
+    try {
+        validated = validateProductionTrust(trust);
+    }
+    catch {
+        throw new AttestationError("Malformed production attestation evidence");
+    }
+    const verified = await verifyEvidence(token, binding, validated, now);
+    if (!validated.imageDigests.includes(verified.imageDigest))
+        throw new AttestationError("Invalid production attestation claims or binding");
+    return verified;
+}
+export async function verifyWorkloadEvidence(token, binding, policy, now = Math.floor(Date.now() / 1000)) {
+    let validated;
+    try {
+        validated = validateWorkloadPolicy(policy);
+    }
+    catch {
+        throw new AttestationError("Malformed production attestation evidence");
+    }
+    return verifyEvidence(token, binding, validated, now);
+}
+async function authenticate(token, binding, roots, now) {
+    try {
+        productionEvidence.parse({ version: PRODUCTION_EVIDENCE_VERSION, token });
+        if (!Number.isSafeInteger(now))
+            throw new Error();
+        evidenceBinding.parse(binding);
+        const [encodedHeader, encodedPayload, signature] = token.split(".");
+        const header = headerSchema.parse(JSON.parse(decodeBase64url(encodedHeader).toString("utf8")));
+        const payload = decodeBase64url(encodedPayload);
+        const chain = header.x5c.map(encoded => {
+            const der = Buffer.from(encoded, "base64");
+            if (der.toString("base64") !== encoded)
+                throw new Error();
+            const cert = new X509Certificate(der);
+            if (!cert.raw.equals(der))
+                throw new Error();
+            return cert;
+        });
+        const key = await validateCertificatePath(chain, roots, now);
+        if (!verify("RSA-SHA256", Buffer.from(`${encodedHeader}.${encodedPayload}`), { key, padding: constants.RSA_PKCS1_PADDING }, decodeBase64url(signature))) {
+            throw new AttestationError("Invalid production attestation signature");
+        }
+        return payload;
+    }
+    catch (error) {
+        if (error instanceof AttestationError)
+            throw error;
+        throw new AttestationError("Malformed production attestation evidence");
+    }
+}
+function validateClaimsBinding(claims, binding, now) {
+    // The challenge bounds freshness; issuer clock drift gets a small allowance without extending expiry.
+    if (claims.exp <= now || claims.iat > now + ISSUER_CLOCK_SKEW_SECONDS ||
+        claims.nbf > now + ISSUER_CLOCK_SKEW_SECONDS || claims.exp <= claims.iat)
+        throw new Error();
+    const nonces = typeof claims.eat_nonce === "string" ? [claims.eat_nonce] : claims.eat_nonce;
+    if (claims.aud !== binding.audience || nonces.length !== binding.nonces.length ||
+        nonces.some((nonce, index) => nonce !== binding.nonces[index]))
+        throw new Error();
+}
+/**
+ * Reviewed roots authenticate probe facts; this result cannot substitute for workload admission.
+ * The default schema is the strict observed shape; a probe owner can supply its own shape for claims
+ * that Google omits on non-compliant workloads, but authentication and binding are always enforced here.
+ */
+export async function observeGoogleEvidence(token, binding, roots, now = Math.floor(Date.now() / 1000), claimsSchema = observedAttestationClaims) {
+    const payload = await authenticate(token, binding, roots, now);
+    try {
+        const claims = claimsSchema.parse(JSON.parse(payload.toString("utf8")));
+        validateClaimsBinding(claims, binding, now);
+        return { claims };
+    }
+    catch {
+        throw new AttestationError("Invalid production attestation claims or binding");
+    }
+}
+async function verifyEvidence(token, binding, trust, now = Math.floor(Date.now() / 1000)) {
+    const payload = await authenticate(token, binding, trust.roots, now);
+    try {
+        // Claims cannot influence trust selection or the internal identity before authentication above.
+        const claims = googleAttestationClaims.parse(JSON.parse(payload.toString("utf8")));
+        validateClaimsBinding(claims, binding, now);
+        const { container, confidential_space: space } = claims.submods;
+        if (!trust.softwareVersions.includes(claims.swversion[0]) ||
+            !isApprovedHardware(claims.hwmodel, trust.hardwareModels) || !trust.subjects.includes(claims.sub) ||
+            claims.google_service_accounts.some(account => !trust.serviceAccounts.includes(account)) ||
+            !space.support_attributes.includes("STABLE") || !space.support_attributes.includes("USABLE") ||
+            space.support_attributes.some(attribute => !["STABLE", "USABLE"].includes(attribute)))
+            throw new Error();
+        if (!container.image_signatures.some(signature => trust.imageSigningKeyIds.includes(signature.key_id)) ||
+            container.image_signatures.some(signature => Buffer.from(signature.signature, "base64").toString("base64") !== signature.signature))
+            throw new Error();
+        return { iss: GOOGLE_ATTESTATION_ISSUER, imageDigest: container.image_digest, iat: claims.iat, exp: claims.exp };
+    }
+    catch {
+        throw new AttestationError("Invalid production attestation claims or binding");
+    }
+}
+export async function verifyProductionAttestation(evidence, binding, trust, now = Math.floor(Date.now() / 1000)) {
+    return verifyProductionEvidence(evidenceToken(evidence), channelEvidenceBinding(binding), trust, now);
+}
+export async function verifyWorkloadAttestation(evidence, binding, policy, now = Math.floor(Date.now() / 1000)) {
+    return verifyWorkloadEvidence(evidenceToken(evidence), channelEvidenceBinding(binding), policy, now);
+}
+function evidenceToken(evidence) {
+    const parsed = productionEvidence.safeParse(evidence);
+    if (!parsed.success || parsed.data.token.length > MAX_ATTESTATION_BYTES)
+        throw new AttestationError("Malformed production attestation evidence");
+    return parsed.data.token;
+}

package/dist/gatekeeper/trust/hardware.js

@@ -0,0 +1,21 @@
+// Target and preserved rollback hardware are chosen only here, and callers never accept both together; rollback keeps AMD SEV on its original machine.
+const target = Object.freeze({ hwmodel: "GCP_INTEL_TDX", computeType: "TDX", machine: "c3-standard-4",
+    confidentialImage: "projects/confidential-space-images/global/images/confidential-space-260800" });
+const rollback = Object.freeze({ hwmodel: "GCP_AMD_SEV", computeType: "SEV", machine: "n2d-standard-2",
+    confidentialImage: target.confidentialImage });
+export const hardwareModels = [target.hwmodel, rollback.hwmodel];
+export function confidentialHardware(profile = "rollback") {
+    if (profile === "target")
+        return target;
+    if (profile === "rollback")
+        return rollback;
+    throw new Error("Invalid confidential hardware policy");
+}
+export function isApprovedHardware(model, approved) {
+    return approved.length === 1 && hardwareModels.some(value => value === model) && approved[0] === model;
+}
+export function requireSealedRootHardware(config, policy) {
+    if (config.hardwareProfile !== "target" || config.confidentialImage !== target.confidentialImage ||
+        policy && !isApprovedHardware(target.hwmodel, policy.hardwareModels))
+        throw new Error("Sealed root requires reviewed target hardware and host image");
+}

package/dist/gatekeeper/trust/policy.js

@@ -0,0 +1,42 @@
+import { X509Certificate } from "node:crypto";
+import { z } from "zod";
+import { hardwareModels } from "./hardware.js";
+export const workloadZones = ["us-central1-a", "us-central1-b", "us-central1-c", "us-central1-f"];
+const values = (item) => z.array(item).min(1).max(8).refine(list => new Set(list).size === list.length);
+/** The one rule for an acceptable Google root: a self-signed CA, RSA of at least 2048 bits, valid at `now`. */
+export function acceptableGoogleRoot(cert, now = Date.now()) {
+    return cert.ca && cert.checkIssued(cert) && cert.verify(cert.publicKey) &&
+        cert.publicKey.asymmetricKeyType === "rsa" && (cert.publicKey.asymmetricKeyDetails?.modulusLength ?? 0) >= 2048 &&
+        Date.parse(cert.validFrom) <= now && Date.parse(cert.validTo) > now;
+}
+const root = z.string().max(16384).refine(pem => {
+    try {
+        const cert = new X509Certificate(pem);
+        return pem.trim() === cert.toString().trim() && acceptableGoogleRoot(cert);
+    }
+    catch {
+        return false;
+    }
+});
+// Fixed security claims remain owned by the native token contract. This policy selects reviewed allow-lists.
+export const workloadPolicy = z.object({
+    version: z.literal(1), roots: values(root),
+    softwareVersions: values(z.string().regex(/^[0-9]{6,8}$/)),
+    hardwareModels: z.array(z.enum(hardwareModels)).length(1),
+    serviceAccounts: values(z.string().regex(/^[a-z][a-z0-9-]*@[a-z][a-z0-9-]*\.iam\.gserviceaccount\.com$/)),
+    subjects: values(z.string().regex(/^https:\/\/www\.googleapis\.com\/compute\/v1\/projects\/[a-z][a-z0-9-]*\/zones\/[a-z0-9-]+\/instances\/[a-z0-9][a-z0-9-]*$/)
+        .refine(subject => workloadZones.some(zone => subject.includes(`/zones/${zone}/`)))),
+    imageSigningKeyIds: values(z.string().regex(/^[0-9a-f]{64}$/)),
+}).strict();
+const productionTrust = workloadPolicy.extend({
+    imageDigests: z.array(z.string().regex(/^sha256:[0-9a-f]{64}$/)).min(1),
+});
+export function validateWorkloadPolicy(value) {
+    return workloadPolicy.parse(value);
+}
+export function workloadPolicyBytes(value) {
+    return `${JSON.stringify(validateWorkloadPolicy(value), null, 2)}\n`;
+}
+export function validateProductionTrust(value) {
+    return productionTrust.parse(value);
+}

package/dist/gatekeeper/trust/production.json

@@ -0,0 +1,25 @@
+{
+  "version": 1,
+  "roots": [
+    "-----BEGIN CERTIFICATE-----\n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\nuyT5CnJulxSC5CT1\n-----END CERTIFICATE-----"
+  ],
+  "softwareVersions": [
+    "260800"
+  ],
+  "hardwareModels": [
+    "GCP_INTEL_TDX"
+  ],
+  "serviceAccounts": [
+    "relay-runtime@hosted-web-504419.iam.gserviceaccount.com"
+  ],
+  "subjects": [
+    "https://www.googleapis.com/compute/v1/projects/hosted-web-504419/zones/us-central1-a/instances/relay-vm",
+    "https://www.googleapis.com/compute/v1/projects/hosted-web-504419/zones/us-central1-a/instances/relay-staging-vm"
+  ],
+  "imageSigningKeyIds": [
+    "47caa7c1d5184e83548e604e4d74e20ffa3d4682031abfe826267a96e15f7fda"
+  ],
+  "imageDigests": [
+    "sha256:1d7a87dcb421afffba20a563e478801972b48fd9569bfb9377aac29e6b589e79"
+  ]
+}

package/dist/setup-pings/client.js

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { fileURLToPath, URL } from "node:url";
+export { readTelemetrySettings } from "./policy.js";
+export const disabledSetupPings = Object.freeze({ ping() { }, link() { } });
+export const DEFAULT_CONSOLE_URL = "https://app.counterfactlabs.com";
+export function createSetupPings(input, io = {}) {
+    if (!input.settings.enabled)
+        return disabledSetupPings;
+    const { homeDir, origin } = input;
+    let token;
+    const dispatch = (operation) => {
+        try {
+            const child = (io.spawn ?? spawn)(process.execPath, [fileURLToPath(new URL("./worker.js", import.meta.url))], {
+                cwd: "/", env: {}, detached: true, stdio: ["pipe", "ignore", "ignore"],
+            });
+            child.on("error", () => { });
+            const pipe = child.stdin;
+            pipe?.on("error", () => { });
+            child.unref();
+            pipe?.unref();
+            // Tokens stay in this private channel, never in argv or the child environment.
+            pipe?.end(JSON.stringify({ ...operation, token, homeDir, origin, ...(io.allowLoopback ? { allowLoopback: true } : {}) }));
+        }
+        catch { /* Reporting must never change a command's result. */ }
+    };
+    return {
+        ping(step) { dispatch({ kind: "ping", step }); },
+        link(value) { token = value; dispatch({ kind: "link" }); },
+    };
+}

package/dist/setup-pings/contract.js

@@ -0,0 +1,2 @@
+// Generated from counterfact_saas/src/lib/funnel/steps.ts. Do not edit by hand.
+export const SETUP_PING_STEPS = ["mcp_started", "claude_allow_rule_found", "agent_sign_in_started", "first_analysis_started"];

package/dist/setup-pings/policy.js

@@ -0,0 +1,3 @@
+export function readTelemetrySettings(env) {
+    return Object.freeze({ enabled: env.CF_TELEMETRY !== "0" && env.DO_NOT_TRACK !== "1" && env.CI === undefined });
+}

package/dist/setup-pings/state.js

@@ -0,0 +1,261 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, unlink } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { SETUP_PING_STEPS } from "./contract.js";
+const idName = "install-id";
+const linkName = "link.attempted";
+const temporaryName = ".install.tmp";
+const stepName = (step) => `${step}.attempted`;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const hasCode = (error, code) => error?.code === code;
+const sameSlot = (left, right) => left.dev === right.dev && left.ino === right.ino
+    && left.mtimeMs === right.mtimeMs && left.size === right.size;
+class IncompleteStateFile extends Error {
+}
+async function stateDirectory(homeDir, create) {
+    if (!isAbsolute(homeDir) || !(await lstat(homeDir)).isDirectory())
+        throw new Error("Invalid home");
+    let directory = homeDir;
+    for (const part of [".config", "counterfact-labs", "setup-pings"]) {
+        directory = join(directory, part);
+        if (create) {
+            try {
+                await mkdir(directory, { mode: 0o700 });
+            }
+            catch (error) {
+                if (!hasCode(error, "EEXIST"))
+                    throw error;
+            }
+        }
+        const info = await lstat(directory);
+        if (!info.isDirectory())
+            throw new Error("Invalid state directory");
+        if (part === "setup-pings" && (info.mode & 0o777) !== 0o700)
+            throw new Error("State directory is not private");
+    }
+    return directory;
+}
+async function readPrivateFile(path, size) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || (info.mode & 0o777) !== 0o600)
+            throw new Error("Invalid state file");
+        if (info.size < size)
+            throw new IncompleteStateFile("Incomplete state file");
+        if (info.size > size)
+            throw new Error("Invalid state size");
+        // Bound reads even if another process changes the file after stat.
+        const buffer = Buffer.alloc(size + 1);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        if (bytesRead < size)
+            throw new IncompleteStateFile("Incomplete state size");
+        if (bytesRead > size)
+            throw new Error("Invalid state size");
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await file.close();
+    }
+}
+async function readIdentity(directory) {
+    for (let count = 0; count < 25; count++) {
+        try {
+            const value = await readPrivateFile(join(directory, idName), 36);
+            if (value !== undefined && !uuid.test(value))
+                throw new Error("Invalid installation ID");
+            return value;
+        }
+        catch (error) {
+            if (!(error instanceof IncompleteStateFile))
+                throw error;
+            // A delayed stale remover may let a publisher link another writer's unfinished slot.
+            await setTimeout(10);
+        }
+    }
+    throw new Error("Incomplete installation ID publication");
+}
+async function readMarkers(directory) {
+    const steps = [];
+    for (const step of SETUP_PING_STEPS) {
+        if (await readPrivateFile(join(directory, stepName(step)), 0) !== undefined)
+            steps.push(step);
+    }
+    const linked = await readPrivateFile(join(directory, linkName), 0) !== undefined;
+    return { steps, linked };
+}
+async function publishIdentity(directory) {
+    const temporary = join(directory, temporaryName);
+    for (let count = 0; count < 25; count++) {
+        const winner = await readIdentity(directory);
+        if (winner)
+            return winner;
+        let file;
+        try {
+            file = await open(temporary, "wx", 0o600);
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+            const winner = await readIdentity(directory);
+            if (winner)
+                return winner;
+            const slot = await readTemporary(directory);
+            // A worker can exit after writing the UUID but before publishing its link.
+            if (slot?.value)
+                await linkIdentity(directory);
+            else if (slot?.stale)
+                await removeTemporary(directory, slot);
+            else
+                await setTimeout(10);
+            continue;
+        }
+        try {
+            try {
+                await file.writeFile(randomUUID(), "utf8");
+            }
+            finally {
+                await file.close();
+            }
+            await linkIdentity(directory);
+            const installId = await readIdentity(directory);
+            // A delayed stale-slot cleanup can unlink our file before the link is made.
+            if (installId)
+                return installId;
+        }
+        finally {
+            await clearTemporary(directory);
+        }
+    }
+    throw new Error("Incomplete installation ID publication");
+}
+async function linkIdentity(directory) {
+    // A hard link publishes only complete bytes and cannot overwrite a winner.
+    try {
+        await link(join(directory, temporaryName), join(directory, idName));
+    }
+    catch (error) {
+        // A reader may remove the slot after observing the already published ID.
+        if (!hasCode(error, "EEXIST") && !hasCode(error, "ENOENT"))
+            throw error;
+    }
+}
+async function readTemporary(directory) {
+    const temporary = join(directory, temporaryName);
+    for (let count = 0; count < 25; count++) {
+        try {
+            const info = await lstat(temporary);
+            if (!info.isFile() || (info.mode & 0o777) !== 0o600)
+                throw new Error("Invalid publication slot");
+            let contents;
+            try {
+                contents = info.size === 36 ? await readPrivateFile(temporary, 36) : undefined;
+            }
+            catch (error) {
+                // A stale slot may have become a new writer's incomplete file before open.
+                if (!sameSlot(info, await lstat(temporary)))
+                    continue;
+                throw error;
+            }
+            // This exceeds the worker's hard lifetime, so an incomplete writer cannot still be active.
+            return { value: contents && uuid.test(contents) ? contents : undefined, stale: Date.now() - info.mtimeMs > 5000,
+                info };
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return undefined;
+            throw error;
+        }
+    }
+    throw new Error("Installation ID publication keeps changing");
+}
+async function clearTemporary(directory) {
+    for (let count = 0; count < 25; count++) {
+        const slot = await readTemporary(directory);
+        if (!slot)
+            return;
+        // A concurrent creator may still be finishing its slot after an ID was published.
+        if (!slot.value && !slot.stale) {
+            await setTimeout(10);
+            continue;
+        }
+        if (await removeTemporary(directory, slot))
+            return;
+    }
+    throw new Error("Incomplete publication slot");
+}
+async function removeTemporary(directory, slot) {
+    try {
+        const temporary = join(directory, temporaryName);
+        const current = await lstat(temporary);
+        // Another recovering worker may already have replaced the stale slot.
+        if (!sameSlot(current, slot.info))
+            return false;
+        await unlink(temporary);
+    }
+    catch (error) {
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+    return true;
+}
+async function createMarker(directory, name) {
+    try {
+        const file = await open(join(directory, name), "wx", 0o600);
+        await file.close();
+        return true;
+    }
+    catch (error) {
+        if (hasCode(error, "EEXIST"))
+            return false;
+        throw error;
+    }
+}
+export async function claimStep(homeDir, step) {
+    try {
+        if (!SETUP_PING_STEPS.includes(step))
+            return null;
+        const directory = await stateDirectory(homeDir, true);
+        const markers = await readMarkers(directory);
+        let installId = await readIdentity(directory);
+        // A missing ID beside old markers is damaged state, not a new installation.
+        if (!installId && (markers.steps.length || markers.linked))
+            return null;
+        installId ??= await publishIdentity(directory);
+        await clearTemporary(directory);
+        if (markers.steps.includes(step) || !await createMarker(directory, stepName(step)))
+            return null;
+        return { installId };
+    }
+    catch {
+        return null;
+    }
+}
+export async function claimLink(homeDir) {
+    try {
+        const directory = await stateDirectory(homeDir, false);
+        const markers = await readMarkers(directory);
+        const installId = await readIdentity(directory);
+        const step = markers.steps[0];
+        if (!installId || !step || markers.linked)
+            return null;
+        await clearTemporary(directory);
+        if (!await createMarker(directory, linkName))
+            return null;
+        return { installId, step };
+    }
+    catch {
+        return null;
+    }
+}