fullcourtdefense-cli 1.36.2 → 1.36.3

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 {};