Skip to content
Python
5.5 KB
Raw Blame
import { createHash, randomUUID } from "node:crypto";
import path from "node:path";
import { performance } from "node:perf_hooks";
import {
  type BackgroundIntent,
  type BackgroundOwner,
  validateBackgroundIntent,
  validateBackgroundOwner,
} from "./background-operation.js";
import {
  planUserService,
  type RuntimeInstallLayout,
  type RuntimeServicePlan,
  runtimeInstallLayout,
} from "./service-plan.js";

interface ArtifactIdentity {
  digest: string;
  version: string;
  root: string;
}
export interface TrustedBackgroundPlan {
  intent: BackgroundIntent;
  layout: RuntimeInstallLayout;
  service: RuntimeServicePlan;
  artifact: ArtifactIdentity;
  owner: BackgroundOwner;
  uid: number;
}
export interface BackgroundPreview {
  intent: BackgroundIntent;
  version: string;
  startAtLogin: boolean;
}
interface Entry {
  plan: TrustedBackgroundPlan;
  expires: number;
  consumed: boolean;
}

/** Short-lived trusted plan registry; never accepts executable paths from renderer.
 * It does not attest artifact bytes or OS state; callers verify those separately.
 * Reopened-process recovery reconstructs plans from trusted installed artifacts,
 * not from public previews. No unverified preview can restore this registry.
 */
export class BackgroundPlanRegistry {
  private readonly entries = new Map<string, Entry>();
  private readonly owner: BackgroundOwner;
  private readonly layout: RuntimeInstallLayout;
  private lastTime = -Infinity;
  constructor(
    owner: BackgroundOwner,
    layout: RuntimeInstallLayout,
    private readonly uid: number,
    private readonly options: { clock?: () => number } = {},
  ) {
    validateBackgroundOwner(owner);
    if (layout.platform !== "darwin" || !Number.isSafeInteger(uid) || uid < 1)
      throw Error("background_plan_platform_unverified");
    if (!path.isAbsolute(layout.home) || !path.isAbsolute(layout.installRoot))
      throw Error("background_plan_layout_invalid");
    const expected = runtimeInstallLayout({
      platform: layout.platform,
      home: layout.home,
      installRoot: layout.installRoot,
      dataDir: layout.dataDir,
    });
    if (
      Object.keys(layout).length !== Object.keys(expected).length ||
      Object.entries(expected).some(
        ([key, value]) => layout[key as keyof RuntimeInstallLayout] !== value,
      )
    )
      throw Error("background_plan_layout_invalid");
    this.owner = Object.freeze({ ...owner });
    this.layout = Object.freeze({ ...layout });
  }
  create(
    action: BackgroundIntent["action"],
    expectedRevision: number,
    artifact: ArtifactIdentity,
  ): BackgroundPreview {
    const now = this.now();
    for (const [key, entry] of this.entries)
      if (entry.expires <= now) this.entries.delete(key);
    if (this.entries.size >= 16) throw Error("background_plan_capacity");
    if (
      !/^[a-f0-9]{64}$/.test(artifact.digest) ||
      !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(artifact.version) ||
      !path.isAbsolute(artifact.root)
    )
      throw Error("background_plan_artifact_invalid");
    const service = planUserService(this.layout, { uid: this.uid });
    const planDigest = createHash("sha256")
      .update(
        JSON.stringify([
          "background-plan-v1",
          this.owner.userId,
          this.owner.runtimeId,
          this.uid,
          Object.keys(this.layout)
            .sort()
            .map((key) => [
              key,
              this.layout[key as keyof RuntimeInstallLayout],
            ]),
          service,
          action,
          artifact.digest,
          artifact.version,
          artifact.root,
        ]),
      )
      .digest("hex");
    const intent = {
      operationId: randomUUID(),
      expectedRevision,
      action,
      planDigest,
      artifactDigest: artifact.digest,
    };
    validateBackgroundIntent(intent);
    this.entries.set(intent.operationId, {
      plan: structuredClone({
        intent,
        layout: this.layout,
        service,
        artifact,
        owner: this.owner,
        uid: this.uid,
      }),
      expires: now + 300,
      consumed: false,
    });
    return {
      intent: { ...intent },
      version: artifact.version,
      startAtLogin: action === "enable",
    };
  }
  resolve(intent: BackgroundIntent): TrustedBackgroundPlan {
    const entry = this.entry(intent);
    if (entry.consumed) throw Error("background_plan_consumed");
    return structuredClone(entry.plan);
  }
  markApplying(intent: BackgroundIntent): void {
    const entry = this.entry(intent);
    if (entry.consumed) throw Error("background_plan_consumed");
    entry.consumed = true;
  }
  inspect(intent: BackgroundIntent): TrustedBackgroundPlan | null {
    try {
      return structuredClone(this.entry(intent).plan);
    } catch {
      return null;
    }
  }
  private entry(intent: BackgroundIntent): Entry {
    validateBackgroundIntent(intent);
    const now = this.now(),
      entry = this.entries.get(intent.operationId);
    if (!entry || entry.expires <= now) throw Error("background_plan_expired");
    const saved = entry.plan.intent;
    if (
      saved.action !== intent.action ||
      saved.expectedRevision !== intent.expectedRevision ||
      saved.planDigest !== intent.planDigest ||
      saved.artifactDigest !== intent.artifactDigest
    )
      throw Error("background_plan_changed");
    return entry;
  }
  private now(): number {
    const now = (this.options.clock ?? (() => performance.now() / 1000))();
    if (!Number.isFinite(now) || now < this.lastTime)
      throw Error("background_plan_clock_invalid");
    this.lastTime = now;
    return now;
  }
}