@phigon/observer 8.2.0 → 8.3.0

package/dist/src/server-clock.js

@@ -0,0 +1,72 @@
+/**
+ * The server's idea of the time, estimated from the times it stamps on the
+ * stream (acknowledgements and policies). Remote commands carry an expiry in
+ * server time, so judging it by a computer clock that is a few minutes off
+ * would reject or extend every command.
+ *
+ * Each sample is the server's stamp minus the local time it arrived, which
+ * is the true offset less the one-way network delay: well under a second,
+ * against command windows of minutes. The estimate is the median of recent
+ * samples, so one odd stamp does not move it, and it is bounded so a broken
+ * stamp cannot move the clock arbitrarily far.
+ */
+export class ServerClock {
+    #now;
+    #maxCorrectionMs;
+    #largeSkewMs;
+    #onLargeSkew;
+    #samples = [];
+    #offsetMs = 0;
+    // The offset last reported as large, so a steady skew is reported once.
+    #reportedOffsetMs;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+        this.#maxCorrectionMs = options.maxCorrectionMs ?? maxCorrectionMs;
+        this.#largeSkewMs = options.largeSkewMs ?? largeSkewMs;
+        this.#onLargeSkew = options.onLargeSkew ?? (() => undefined);
+    }
+    /** Records a server timestamp that arrived just now. */
+    observe(serverTime) {
+        const sample = serverTime.getTime() - this.#now();
+        if (!Number.isFinite(sample))
+            return;
+        this.#samples.push(sample);
+        if (this.#samples.length > retainedSamples)
+            this.#samples.shift();
+        const sorted = [...this.#samples].sort((left, right) => left - right);
+        const median = sorted[Math.floor(sorted.length / 2)] ?? 0;
+        this.#offsetMs = Math.max(-this.#maxCorrectionMs, Math.min(this.#maxCorrectionMs, median));
+        const large = Math.abs(median) >= this.#largeSkewMs;
+        if (!large) {
+            this.#reportedOffsetMs = undefined;
+        }
+        else if (this.#reportedOffsetMs === undefined ||
+            Math.abs(median - this.#reportedOffsetMs) >= this.#largeSkewMs) {
+            this.#reportedOffsetMs = median;
+            this.#onLargeSkew(median);
+        }
+    }
+    /** How far the server's clock is ahead of this computer's, as applied. */
+    offsetMs() {
+        return this.#offsetMs;
+    }
+    /** The current time on the server's clock, in epoch milliseconds. */
+    now() {
+        return this.#now() + this.#offsetMs;
+    }
+}
+/** A plain-English description of a clock skew, for status messages. */
+export function describeClockSkew(offsetMs) {
+    const seconds = Math.round(Math.abs(offsetMs) / 1_000);
+    const amount = seconds >= 120
+        ? `${Math.round(seconds / 60)} minutes`
+        : `${seconds} seconds`;
+    return `This computer's clock is ${amount} ${offsetMs > 0 ? "behind" : "ahead of"} the workspace server. ` +
+        "Remote commands are timed by the server's clock; correct the computer's clock to keep other tools accurate.";
+}
+const retainedSamples = 9;
+// Covers a clock set to the wrong time zone, as on a computer that also
+// starts another operating system, without trusting a wildly wrong stamp.
+const maxCorrectionMs = 24 * 3_600_000;
+const largeSkewMs = 60_000;
+//# sourceMappingURL=server-clock.js.map

package/dist/src/server-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-clock.js","sourceRoot":"","sources":["../../src/server-clock.ts"],"names":[],"mappings":"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"}

package/dist/src/service-command.d.ts

@@ -0,0 +1,20 @@
+import { type ObserverConfig } from "./config.js";
+import { type CommandRunner, type ServiceContext } from "./service.js";
+export type ServiceDependencies = Readonly<{
+    /** Runs schtasks, launchctl or systemctl; tests replace it. */
+    serviceRunner?: CommandRunner;
+    /** The operating system to install for; tests replace it. */
+    platform?: NodeJS.Platform;
+    /** How long to wait for a stopping observer to let go of its data directory. */
+    stopTimeoutMs?: number;
+    /** The home folder a LaunchAgent or user unit goes under; tests replace it. */
+    homeDirectory?: string;
+}>;
+type Output = Readonly<{
+    stdout: (value: string) => void;
+}>;
+export declare function serviceContext(config: ObserverConfig, environment: NodeJS.ProcessEnv, dependencies?: ServiceDependencies): ServiceContext;
+/** `service install | uninstall | status`. */
+export declare function runServiceCommand(flags: readonly string[], config: ObserverConfig, environment: NodeJS.ProcessEnv, output: Output, json: boolean, dependencies?: ServiceDependencies): Promise<number>;
+export {};
+//# sourceMappingURL=service-command.d.ts.map

package/dist/src/service-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-command.d.ts","sourceRoot":"","sources":["../../src/service-command.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAMhF,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH,KAAK,MAAM,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC,CAAC;AAE5D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,CAAC,UAAU,EAC9B,YAAY,GAAE,mBAAwB,GACrC,cAAc,CAuBhB;AAwCD,8CAA8C;AAC9C,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,CAAC,UAAU,EAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,YAAY,GAAE,mBAAwB,GACrC,OAAO,CAAC,MAAM,CAAC,CAgEjB"}

package/dist/src/service-command.js

@@ -0,0 +1,136 @@
+import { homedir, userInfo } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { contentOutsideProfileMessage } from "./config.js";
+import { FileCredentialStore } from "./credential-store.js";
+import { InstanceLock } from "./instance-lock.js";
+import { logFilePath } from "./observer-log.js";
+import { OBSERVER_CONSENT_POLICY_VERSION } from "./pair.js";
+import { currentUserSID } from "./private-directory.js";
+import { installService, runCommand, serviceDefinitionPath, serviceInstalled, serviceName, servicePlatform, serviceSettings, uninstallService, } from "./service.js";
+export function serviceContext(config, environment, dependencies = {}) {
+    const platform = servicePlatform(dependencies.platform ?? process.platform);
+    if (platform === undefined) {
+        throw new Error("Background services are available on Windows, macOS and Linux. Keep phigon-observer run running another way.");
+    }
+    const dataDirectory = resolve(config.dataDirectory);
+    const fallback = resolve(join(homedir(), ".phigon", "observer"));
+    const same = (a, b) => platform === "windows" ? a.toLowerCase() === b.toLowerCase() : a === b;
+    const account = userInfo();
+    return Object.freeze({
+        platform,
+        dataDirectory,
+        defaultDataDirectory: same(dataDirectory, fallback),
+        nodePath: process.execPath,
+        entryPath: fileURLToPath(new URL("./entry.js", import.meta.url)),
+        homeDirectory: dependencies.homeDirectory ?? homedir(),
+        user: platform === "windows"
+            ? (currentUserSID() ?? `${environment["USERDOMAIN"] ?? process.env["USERDOMAIN"] ?? ""}\\${account.username}`)
+            : String(account.uid),
+        configHome: environment["XDG_CONFIG_HOME"]?.trim() || undefined,
+        systemRoot: process.env["SystemRoot"] ?? process.env["SYSTEMROOT"],
+        run: dependencies.serviceRunner ?? runCommand,
+    });
+}
+/** Why collection cannot start on this computer, or undefined when it can. */
+async function installRefusal(config) {
+    const credential = await new FileCredentialStore(config.dataDirectory).load();
+    if (credential === null) {
+        return "This computer is not paired, so a background service would have nothing to collect. Pair it with the command from Connect machine, then run service install again.";
+    }
+    if (credential.controlPlaneOrigin !== config.controlPlaneUrl.origin) {
+        return `This computer is paired with ${credential.controlPlaneOrigin}, but the observer is set up for ${config.controlPlaneUrl.origin}. Remove the other control plane setting and try again.`;
+    }
+    if (credential.consentPolicyVersion !== OBSERVER_CONSENT_POLICY_VERSION || credential.consentProfile === undefined) {
+        return "The computer owner's consent is missing or out of date. Pair again with --consent-profile metadata or full, then run service install again.";
+    }
+    if (config.observabilityProfile === "full" && credential.consentProfile !== "full") {
+        return "Full-content collection is outside the consented metadata profile. Install the service with --profile metadata, or pair again with full-activity consent.";
+    }
+    if (config.contentSettingsOutsideProfile.length > 0) {
+        return contentOutsideProfileMessage(config.contentSettingsOutsideProfile);
+    }
+    return undefined;
+}
+async function waitUntilStopped(dataDirectory, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!(await InstanceLock.inspect(dataDirectory)).running)
+            return true;
+        await delay(250);
+    }
+    return !(await InstanceLock.inspect(dataDirectory)).running;
+}
+function restartNote(context) {
+    return context.platform === "windows"
+        ? "It starts when you sign in, and again within a minute if it stops."
+        : context.platform === "macos"
+            ? "It starts when you sign in, and launchd starts it again if it stops."
+            : "It starts when you sign in, and systemd restarts it if it fails.";
+}
+/** `service install | uninstall | status`. */
+export async function runServiceCommand(flags, config, environment, output, json, dependencies = {}) {
+    const subcommand = flags[0];
+    if (subcommand !== "install" && subcommand !== "uninstall" && subcommand !== "status") {
+        throw new Error("service requires one of: install, uninstall, or status. Run phigon-observer help for usage.");
+    }
+    const context = serviceContext(config, environment, dependencies);
+    const name = serviceName(context);
+    const logFile = logFilePath(context.dataDirectory);
+    const definition = serviceDefinitionPath(context) ?? name;
+    if (subcommand === "status") {
+        const installed = await serviceInstalled(context);
+        const running = (await InstanceLock.inspect(context.dataDirectory)).running;
+        const state = !installed ? "not_installed" : running ? "running" : "stopped";
+        output.stdout(json
+            ? `${JSON.stringify({ state, installed, running, name, platform: context.platform, definition, dataDirectory: context.dataDirectory, logFile }, null, 2)}\n`
+            : [
+                `Background service: ${!installed ? "not installed" : running ? "installed and running" : "installed and stopped"}`,
+                `Name: ${name}`,
+                ...(installed ? [`Log: ${logFile}`] : []),
+                ...(!installed && running ? ["An observer started by hand is running with this data directory."] : []),
+                "",
+            ].join("\n"));
+        return 0;
+    }
+    if (subcommand === "uninstall") {
+        const removed = await uninstallService(context);
+        const stopped = removed ? await waitUntilStopped(context.dataDirectory, dependencies.stopTimeoutMs ?? 15_000) : true;
+        output.stdout(json
+            ? `${JSON.stringify({ status: removed ? "removed" : "not_installed", name, platform: context.platform, observerStopped: stopped }, null, 2)}\n`
+            : [
+                removed ? `Background service removed: ${name}.` : "The background service was not installed.",
+                ...(removed && !stopped ? ["The observer is still stopping; it exits within a few seconds."] : []),
+                "",
+            ].join("\n"));
+        return 0;
+    }
+    const refusal = await installRefusal(config);
+    if (refusal !== undefined)
+        throw new Error(refusal);
+    const settings = { ...serviceSettings(environment), PHIGON_OBSERVABILITY_PROFILE: config.observabilityProfile };
+    const alreadyRunning = (await InstanceLock.inspect(context.dataDirectory)).running;
+    const result = await installService(context, settings);
+    const notes = [
+        restartNote(context),
+        ...(alreadyRunning
+            ? ["An observer is already running with this data directory. The service takes over when it stops."]
+            : []),
+        ...(context.platform === "linux"
+            ? [`To keep collecting while ${userInfo().username} is signed out, an administrator can run: loginctl enable-linger ${userInfo().username}`]
+            : []),
+    ];
+    output.stdout(json
+        ? `${JSON.stringify({ status: "installed", name, platform: context.platform, definition: result.definition, settingsFile: result.settingsFile, logFile, profile: config.observabilityProfile, notes }, null, 2)}\n`
+        : [
+            `Background service installed: ${name}`,
+            `Collection profile: ${config.observabilityProfile}`,
+            ...notes,
+            `Settings: ${result.settingsFile}`,
+            `Log: ${logFile}`,
+            "",
+        ].join("\n"));
+    return 0;
+}
+//# sourceMappingURL=service-command.js.map

package/dist/src/service-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-command.js","sourceRoot":"","sources":["../../src/service-command.ts"],"names":[],"mappings":"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"}

package/dist/src/service.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The observer as a background service of the signed-in user: a Task
+ * Scheduler task on Windows, a LaunchAgent on macOS and a systemd user unit
+ * on Linux. It runs as that user, not as SYSTEM or root, because it reads
+ * that user's agent files. The definition holds only the Node.js binary,
+ * the observer's entry point and the path of the settings file in the data
+ * directory; settings and the machine key stay in the data directory.
+ */
+export type ServicePlatform = "windows" | "macos" | "linux";
+export type CommandResult = Readonly<{
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** The program does not exist on this computer. */
+    missing?: boolean;
+}>;
+/** Runs a program without a shell. Tests replace it; nothing is installed. */
+export type CommandRunner = (command: string, args: readonly string[]) => Promise<CommandResult>;
+export declare const serviceSettingsFileName = "service-settings.json";
+export type ServiceContext = Readonly<{
+    platform: ServicePlatform;
+    /** Absolute data directory the service runs with. */
+    dataDirectory: string;
+    /** Whether that is the default ~/.phigon/observer, which keeps the plain name. */
+    defaultDataDirectory: boolean;
+    /** The Node.js binary and observer entry point that ran `service install`. */
+    nodePath: string;
+    entryPath: string;
+    homeDirectory: string;
+    /** Windows: the account's SID or DOMAIN\user. macOS: the numeric uid. */
+    user: string;
+    /** Linux: $XDG_CONFIG_HOME when it is set. */
+    configHome?: string | undefined;
+    /** Windows: %SystemRoot%. */
+    systemRoot?: string | undefined;
+    run: CommandRunner;
+    now?: () => Date;
+    /** Waits between retries; tests make it instant. */
+    wait?: (ms: number) => Promise<void>;
+}>;
+export declare function servicePlatform(platform: NodeJS.Platform): ServicePlatform | undefined;
+/**
+ * The service's name. One observer runs per data directory, so a directory
+ * other than the default gets its own service, named with a short digest
+ * of its path.
+ */
+export declare function serviceName(context: Pick<ServiceContext, "platform" | "dataDirectory" | "defaultDataDirectory">): string;
+export declare function serviceSettingsPath(dataDirectory: string): string;
+/** Where the definition file lives; Windows keeps it in Task Scheduler. */
+export declare function serviceDefinitionPath(context: ServiceContext): string | undefined;
+/** The command the service runs. */
+export declare function serviceCommand(context: ServiceContext): readonly string[];
+/**
+ * Task Scheduler XML. The task starts at sign-in and is retried every minute
+ * (a running copy is left alone), so an observer that stops is started again
+ * within a minute. conhost --headless keeps a console window from opening;
+ * it does not pass on the exit code, so the minute trigger, not the failure
+ * setting, is what restarts it.
+ */
+export declare function windowsTaskXml(context: ServiceContext): string;
+/** A LaunchAgent that starts at sign-in and is started again if it stops. */
+export declare function launchAgentPlist(context: ServiceContext): string;
+/** A systemd user unit, restarted when it fails. */
+export declare function systemdUserUnit(context: ServiceContext): string;
+/**
+ * The settings from `environment` that the service needs to behave like
+ * this terminal: PHIGON_* settings (never a token or password), PATH for
+ * finding agents, proxy and certificate settings, and the folders some
+ * agents keep their records in. The data directory is where the file is.
+ */
+export declare function serviceSettings(environment: NodeJS.ProcessEnv): Record<string, string>;
+export declare function writeServiceSettings(dataDirectory: string, settings: Readonly<Record<string, string>>): Promise<string>;
+/** Reads and checks the settings file; anything unexpected is refused. */
+export declare function readServiceSettings(path: string): Promise<Record<string, string>>;
+export declare class ServiceError extends Error {
+}
+export type ServiceInstallResult = Readonly<{
+    name: string;
+    platform: ServicePlatform;
+    /** The definition file, or the Task Scheduler task name on Windows. */
+    definition: string;
+    settingsFile: string;
+}>;
+/**
+ * Installs the service, replacing an earlier definition of the same name,
+ * and starts it. The caller checks pairing and consent first.
+ */
+export declare function installService(context: ServiceContext, settings: Readonly<Record<string, string>>): Promise<ServiceInstallResult>;
+export declare function serviceInstalled(context: ServiceContext): Promise<boolean>;
+/** Stops the running service without removing it. Returns false when it is not installed. */
+export declare function stopService(context: ServiceContext): Promise<boolean>;
+/** Starts the service again after `stopService`. */
+export declare function startService(context: ServiceContext): Promise<void>;
+/** Stops and removes the service and its settings file. Returns false when it was not installed. */
+export declare function uninstallService(context: ServiceContext): Promise<boolean>;
+/** Runs a program with execFile: no shell, no window, a time limit. */
+export declare const runCommand: CommandRunner;
+//# sourceMappingURL=service.d.ts.map

package/dist/src/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}