fullcourtdefense-cli 1.36.2 → 1.36.4

package/dist/identityRecovery.d.ts

@@ -0,0 +1,50 @@
+import type { FlushFailure } from './telemetry';
+/**
+ * Server-assisted identity recovery (#1853).
+ *
+ * When events:batch answers 409 MACHINE_NOT_ENROLLED, the id this machine
+ * sends is not the one its shield is enrolled under (a stale fallback id
+ * after a blocked native read). The daemon asks the backend which machine its
+ * per-machine shield is bound to. The backend answers only for EXACTLY one
+ * live machine record bound to this shield, in the shield's organization,
+ * with this hostname, and only to a caller holding the shield key — it never
+ * lets the caller choose an id. The answer is pinned as `recovered`.
+ */
+export declare const MACHINE_NOT_ENROLLED = "MACHINE_NOT_ENROLLED";
+/** Daemon log wording for a heartbeat that did not land: refused by the backend vs never reached it. */
+export declare function describeHeartbeatMiss(failure: FlushFailure | undefined): string;
+export type RecoveryResult = {
+    ok: true;
+    machineId: string;
+} | {
+    ok: false;
+    status?: number;
+    code?: string;
+    error: string;
+};
+/** POST /api/cli/machines/identity-recovery. Requires the shield key; never throws. */
+export declare function requestIdentityRecovery(input: {
+    apiUrl: string;
+    shieldId: string;
+    shieldKey?: string;
+    hostname: string;
+    offeredIds: string[];
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<RecoveryResult>;
+/**
+ * Daemon hook: after a refused heartbeat, recover the enrolled id when the
+ * refusal is MACHINE_NOT_ENROLLED. At most once per 15 min per process.
+ * Returns true when the machine now uses a different (recovered) id.
+ */
+export declare function recoverIdentityAfterRefusal(input: {
+    failure: FlushFailure | undefined;
+    apiUrl: string;
+    shieldId?: string;
+    shieldKey?: string;
+    log: (line: string) => void;
+    now?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<boolean>;
+/** Test seam: forget the recovery throttle. */
+export declare function resetIdentityRecoveryThrottle(): void;

package/dist/identityRecovery.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MACHINE_NOT_ENROLLED = void 0;
+exports.describeHeartbeatMiss = describeHeartbeatMiss;
+exports.requestIdentityRecovery = requestIdentityRecovery;
+exports.recoverIdentityAfterRefusal = recoverIdentityAfterRefusal;
+exports.resetIdentityRecoveryThrottle = resetIdentityRecoveryThrottle;
+const machineIdentity_1 = require("./machineIdentity");
+/**
+ * Server-assisted identity recovery (#1853).
+ *
+ * When events:batch answers 409 MACHINE_NOT_ENROLLED, the id this machine
+ * sends is not the one its shield is enrolled under (a stale fallback id
+ * after a blocked native read). The daemon asks the backend which machine its
+ * per-machine shield is bound to. The backend answers only for EXACTLY one
+ * live machine record bound to this shield, in the shield's organization,
+ * with this hostname, and only to a caller holding the shield key — it never
+ * lets the caller choose an id. The answer is pinned as `recovered`.
+ */
+exports.MACHINE_NOT_ENROLLED = 'MACHINE_NOT_ENROLLED';
+const RECOVERY_RETRY_MS = 15 * 60_000;
+let lastAttemptAt = 0;
+/** Daemon log wording for a heartbeat that did not land: refused by the backend vs never reached it. */
+function describeHeartbeatMiss(failure) {
+    if (failure?.kind === 'http' && failure.status) {
+        const what = failure.code === exports.MACHINE_NOT_ENROLLED
+            ? 'machine not enrolled under this id'
+            : failure.code || failure.error || 'request refused';
+        return `backend refused the heartbeat (HTTP ${failure.status}: ${what}) — daemon liveness was not recorded`;
+    }
+    if (failure?.kind === 'locked')
+        return 'heartbeat skipped: another flusher held the spool lock — daemon liveness was not recorded';
+    const detail = failure?.error ? ` (${failure.error})` : '';
+    return `heartbeat did not reach the backend${detail} — daemon liveness was not recorded`;
+}
+/** POST /api/cli/machines/identity-recovery. Requires the shield key; never throws. */
+async function requestIdentityRecovery(input) {
+    if (!input.shieldKey)
+        return { ok: false, error: 'no shield key on this machine — recovery needs it' };
+    try {
+        const resp = await (input.fetchImpl || fetch)(`${input.apiUrl}/api/cli/machines/identity-recovery`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'x-shield-key': input.shieldKey },
+            body: JSON.stringify({ shieldId: input.shieldId, hostname: input.hostname, offeredIds: input.offeredIds }),
+            signal: AbortSignal.timeout(input.timeoutMs ?? 8000),
+        });
+        const body = await resp.json().catch(() => ({}));
+        const machineId = typeof body.data?.machineId === 'string' ? body.data.machineId.toLowerCase() : '';
+        if (resp.ok && body.success && /^[0-9a-f]{16,64}$/.test(machineId))
+            return { ok: true, machineId };
+        return { ok: false, status: resp.status, code: body.code, error: body.error || `HTTP ${resp.status}` };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Daemon hook: after a refused heartbeat, recover the enrolled id when the
+ * refusal is MACHINE_NOT_ENROLLED. At most once per 15 min per process.
+ * Returns true when the machine now uses a different (recovered) id.
+ */
+async function recoverIdentityAfterRefusal(input) {
+    if (input.failure?.code !== exports.MACHINE_NOT_ENROLLED || !input.shieldId)
+        return false;
+    if ((process.env.FCD_MACHINE_ID || '').trim())
+        return false;
+    const now = input.now ?? Date.now();
+    if (now - lastAttemptAt < RECOVERY_RETRY_MS)
+        return false;
+    lastAttemptAt = now;
+    const identity = (0, machineIdentity_1.getMachineIdentity)();
+    const pin = (0, machineIdentity_1.readPinnedIdentity)();
+    const offeredIds = [...new Set([identity.machineId, pin?.machineId].filter((id) => !!id).map(machineIdentity_1.shortMachineId))];
+    const result = await requestIdentityRecovery({
+        apiUrl: input.apiUrl,
+        shieldId: input.shieldId,
+        shieldKey: input.shieldKey,
+        hostname: identity.hostname,
+        offeredIds,
+        fetchImpl: input.fetchImpl,
+    });
+    if (!result.ok) {
+        input.log(`Identity recovery: the backend did not name an enrolled machine for this shield (${result.code || result.error}) — this machine keeps id ${(0, machineIdentity_1.shortMachineId)(identity.machineId)}; re-enroll with \`fullcourtdefense onboard --token <token>\` if it persists.`);
+        return false;
+    }
+    if (result.machineId === identity.machineId)
+        return false;
+    const outcome = (0, machineIdentity_1.confirmMachineIdentity)(result.machineId, 'recovered');
+    if (outcome === 'conflict') {
+        input.log(`Identity recovery: the backend names ${(0, machineIdentity_1.shortMachineId)(result.machineId)} but this machine holds a confirmed id ${(0, machineIdentity_1.shortMachineId)(identity.machineId)} — kept; reported as machine_id_conflict.`);
+        return false;
+    }
+    input.log(`Identity recovery: this machine was sending id ${(0, machineIdentity_1.shortMachineId)(identity.machineId)}; its shield is enrolled as ${(0, machineIdentity_1.shortMachineId)(result.machineId)} — pinned (${outcome}).`);
+    return (0, machineIdentity_1.getMachineIdentity)().machineId === result.machineId;
+}
+/** Test seam: forget the recovery throttle. */
+function resetIdentityRecoveryThrottle() {
+    lastAttemptAt = 0;
+}

package/dist/machineIdentity.d.ts

@@ -11,14 +11,102 @@ export interface MachineIdentity {
     platform: NodeJS.Platform;
     /** Friendly OS label, e.g. `Windows 11`, `macOS 14`, `Ubuntu 22.04`. */
     osFriendly: string;
+    /** Where `machineId` came from (`ci` = FCD_MACHINE_ID override). */
+    idSource?: IdentitySource | 'ci';
+    /** True when the backend has accepted this id (enrollment / heartbeat / recovery). */
+    idConfirmed?: boolean;
 }
+/** Origin of a pinned id. `enrollment` and `recovered` are backend-confirmed by definition. */
+export type IdentitySource = 'native' | 'fallback' | 'enrollment' | 'recovered';
+export interface PinnedIdentity {
+    schema: 1;
+    machineId: string;
+    source: IdentitySource;
+    firstSeen: string;
+    updatedAt: string;
+    /** Set once the backend accepted this id. */
+    confirmedAt?: string;
+    /** Normalized hostname at pin time; a change allows one native re-check (clone / rename). */
+    hostname?: string;
+}
+/**
+ * How far resolution may go to read the OS id:
+ *  - `unpinned` (every process): only when there is no pin, throttled;
+ *  - `heal` (daemon boot): also re-check an unconfirmed fallback pin, throttled;
+ *  - `force` (enrollment): re-check an unconfirmed pin regardless of the throttle.
+ */
+export type NativeReadMode = 'unpinned' | 'heal' | 'force';
+export interface IdentityReconcileReport {
+    machineId: string;
+    source: IdentitySource;
+    confirmed: boolean;
+    /** A native read was attempted by this call. */
+    probed: boolean;
+    probeError?: string;
+    /** The pin moved from an unconfirmed fallback id to the native one. */
+    healed?: {
+        from: string;
+        to: string;
+    };
+    /** Native disagrees with a backend-confirmed pin (kept). */
+    conflict?: {
+        pinned: string;
+        native: string;
+    };
+}
+interface IdentityDeps {
+    execFileSync: (file: string, args: string[], options: {
+        encoding: 'utf8';
+        windowsHide: boolean;
+        timeout: number;
+    }) => string;
+    platform: () => NodeJS.Platform;
+    now: () => number;
+    uptimeSeconds: () => number;
+    hostname: () => string;
+    /** Linux: /etc/machine-id, else /var/lib/dbus/machine-id (a file read, no spawn). */
+    linuxMachineId: () => string | undefined;
+}
+/** Test seam: replace the spawn / clock / platform, and forget the cached identity. */
+export declare function __setMachineIdentityDepsForTest(overrides?: Partial<IdentityDeps>): void;
+/** Forget the in-process identity (the pin changed). */
+export declare function resetMachineIdentityCache(): void;
 /** Normalize a hostname: strip `.local`/domain suffix, lowercase. */
 export declare function normalizeHostname(raw: string): string;
+/** First 8 hex chars — how ids appear in logs, distress details and recovery requests. */
+export declare function shortMachineId(machineId: string): string;
 /**
- * Compute (and cache) the stable machine identity. The raw OS id is hashed
+ * CLI commands that inspect or remove the installation: `uninstall-*`,
+ * `*-status`, the removal commands, and `--uninstall` / `--unschedule` /
+ * `--status` runs of the daemon, auto-protect and discover.
+ */
+export declare function isIdentityReadOnlyCommand(command: string, flags?: Record<string, string | undefined>): boolean;
+/**
+ * Inspect / remove commands (verify-removed, uninstall, doctor, …): resolve
+ * from what is on disk, write nothing and never spawn the native read.
+ */
+export declare function setMachineIdentityReadOnly(on: boolean): void;
+export declare function isPinConfirmed(pin: PinnedIdentity): boolean;
+export declare function readPinnedIdentity(): PinnedIdentity | undefined;
+/**
+ * The stable machine identity (cached per process). The raw OS id is hashed
  * (SHA-256, 32 hex chars) so we never transmit the raw hardware UUID.
  */
 export declare function getMachineIdentity(): MachineIdentity;
+/**
+ * Re-resolve with a wider native-read allowance: the daemon at boot (`heal`)
+ * and enrollment (`force`). Replaces the cached identity.
+ */
+export declare function reconcileMachineIdentity(mode: Exclude<NativeReadMode, 'unpinned'>): IdentityReconcileReport;
+export type ConfirmOutcome = 'pinned' | 'already' | 'conflict' | 'skipped';
+/**
+ * Record that the backend accepted `machineId` for this machine:
+ *  - `enrollment`: the enroll call succeeded — authoritative, always pinned;
+ *  - `heartbeat`: events:batch returned 200 for the id this process uses;
+ *  - `recovered`: the backend named the machine bound to this shield. Never
+ *    replaces a different confirmed id (records `machine_id_conflict`).
+ */
+export declare function confirmMachineIdentity(machineId: string, how: 'enrollment' | 'heartbeat' | 'recovered'): ConfirmOutcome;
 export type LocalMachineKind = 'workstation' | 'ci' | 'workload';
 /**
  * Which KIND of fleet machine this process belongs to — the value the policy
@@ -53,3 +141,4 @@ export declare function stampRuntimeIdentityContext<T extends Record<string, str
 }): T;
 /** Suggested per-machine Shield name, e.g. `boazl@boaz-pc · Windows 11`. */
 export declare function suggestedShieldName(identity?: MachineIdentity): string;
+export {};