Skip to content
Python
6.4 KB
Raw Blame
import { constants } from "node:fs";
import { lstat, open } from "node:fs/promises";
import path from "node:path";
import {
  planUserService,
  RUNTIME_SERVICE_ID,
  type RuntimeInstallLayout,
} from "./service-plan.js";

export type BackgroundRegistration =
  | "absent"
  | "registered"
  | "requires_approval"
  | "disabled_by_system"
  | "conflict"
  | "unknown";
export type LegacyBackgroundRegistration =
  | "not_registered"
  | "enabled"
  | "requires_approval"
  | "disabled_by_system"
  | "unknown";

export interface BackgroundRegistrationStatus {
  serviceId: string;
  file: "absent" | "managed" | "conflict" | "unknown";
  registration: BackgroundRegistration;
  runtime: "not_checked";
  reason: string | null;
}

/** Read-only declaration/registration projection; never installs or starts.
 * OS observation must come from the trusted control layer, not renderer input.
 * A managed plist is not proof of OS registration, Core/Broker health or consent.
 */
export async function inspectBackgroundRegistration(
  layout: RuntimeInstallLayout,
  options: {
    uid?: number;
    legacy?: LegacyBackgroundRegistration;
    observe?: (serviceId: string) => Promise<BackgroundRegistration>;
  } = {},
): Promise<BackgroundRegistrationStatus> {
  const base: BackgroundRegistrationStatus = {
    serviceId: RUNTIME_SERVICE_ID,
    file: "unknown",
    registration: "unknown",
    runtime: "not_checked",
    reason: null,
  };
  if (layout.platform !== "darwin")
    return { ...base, reason: "background_platform_unverified" };
  const plan = planUserService(layout, { uid: options.uid });
  if (!plan.service_file || plan.status !== "ready") {
    return { ...base, reason: plan.blocked_reason };
  }
  // The label is derived from the install root, so observe the one this plan
  // actually declares rather than the canonical daily label.
  const serviceId = plan.service_id;
  const before = await declarationStamp(plan.service_file.path);
  const file = await inspectDeclaration(
    plan.service_file.path,
    plan.service_file.content,
  );
  if (file === "conflict")
    return {
      ...base,
      file,
      registration: "conflict",
      reason: "service_declaration_conflict",
    };
  if (file === "unknown")
    return { ...base, file, reason: "service_declaration_unavailable" };
  if (options.legacy === undefined || options.legacy === "unknown") {
    return { ...base, file, reason: "legacy_registration_unknown" };
  }
  if (options.legacy !== "not_registered") {
    return {
      ...base,
      file,
      registration: "conflict",
      reason: "legacy_registration_conflict",
    };
  }
  if (!options.observe)
    return { ...base, file, reason: "system_registration_not_checked" };
  try {
    const registration = await options.observe(serviceId);
    const after = await declarationStamp(plan.service_file.path);
    if (before === undefined || after === undefined || before !== after) {
      return {
        ...base,
        serviceId,
        file: "unknown",
        reason: "service_declaration_changed",
      };
    }
    if (
      ![
        "absent",
        "registered",
        "requires_approval",
        "disabled_by_system",
        "conflict",
        "unknown",
      ].includes(registration)
    ) {
      return { ...base, file, reason: "system_registration_unavailable" };
    }
    if (
      file === "absent" &&
      registration !== "absent" &&
      registration !== "unknown"
    ) {
      return {
        ...base,
        serviceId,
        file,
        registration: "conflict",
        reason: "system_registration_without_declaration",
      };
    }
    return { ...base, serviceId, file, registration };
  } catch {
    return {
      ...base,
      serviceId,
      file,
      reason: "system_registration_unavailable",
    };
  }
}

async function inspectDeclaration(
  target: string,
  expected: string,
): Promise<BackgroundRegistrationStatus["file"]> {
  try {
    const metadata = await lstat(target);
    const parent = await lstat(path.dirname(target));
    const uid = process.getuid?.();
    if (
      !metadata.isFile() ||
      metadata.isSymbolicLink() ||
      metadata.nlink !== 1 ||
      metadata.size > 65536 ||
      (metadata.mode & 0o077) !== 0 ||
      (uid !== undefined && metadata.uid !== uid) ||
      !parent.isDirectory() ||
      parent.isSymbolicLink() ||
      (parent.mode & 0o022) !== 0 ||
      (uid !== undefined && parent.uid !== uid)
    )
      return "conflict";
    const handle = await open(
      target,
      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
    );
    try {
      const opened = await handle.stat();
      if (
        !opened.isFile() ||
        opened.nlink !== 1 ||
        opened.mode !== metadata.mode ||
        opened.uid !== metadata.uid ||
        opened.ino !== metadata.ino ||
        opened.dev !== metadata.dev
      )
        return "unknown";
      const buffer = Buffer.alloc(65537);
      let total = 0;
      while (total < buffer.length) {
        const { bytesRead } = await handle.read(
          buffer,
          total,
          buffer.length - total,
          total,
        );
        if (!bytesRead) break;
        total += bytesRead;
      }
      if (total !== metadata.size || total > 65536) return "unknown";
      const text = new TextDecoder("utf-8", { fatal: true }).decode(
        buffer.subarray(0, total),
      );
      const current = await lstat(target);
      if (
        current.ino !== metadata.ino ||
        current.dev !== metadata.dev ||
        current.size !== metadata.size ||
        current.mtimeMs !== metadata.mtimeMs ||
        current.ctimeMs !== metadata.ctimeMs ||
        current.mode !== metadata.mode ||
        current.uid !== metadata.uid ||
        current.nlink !== 1
      )
        return "unknown";
      return text === expected ? "managed" : "conflict";
    } finally {
      await handle.close();
    }
  } catch (error) {
    const code = (error as NodeJS.ErrnoException).code;
    if (code === "ENOENT") return "absent";
    if (code === "ELOOP") return "conflict";
    return "unknown";
  }
}

async function declarationStamp(
  target: string,
): Promise<string | null | undefined> {
  try {
    const info = await lstat(target);
    return JSON.stringify([
      info.dev,
      info.ino,
      info.mode,
      info.uid,
      info.nlink,
      info.size,
      info.mtimeMs,
      info.ctimeMs,
    ]);
  } catch (error) {
    return (error as NodeJS.ErrnoException).code === "ENOENT"
      ? null
      : undefined;
  }
}