@hienlh/ppm 0.18.7 → 0.18.9

package/src/services/system-metrics/kill-guard.ts

@@ -0,0 +1,124 @@
+/**
+ * Decides whether a process may be ended. Pure — the same function fills
+ * `ProcessInfo.protected` for the UI and gates the kill route, so the disabled
+ * button and the 403 cannot disagree.
+ *
+ * Names are compared lowercased and extension-free, which is why no literal
+ * below carries `.exe`: one list matches Windows, Linux and macOS.
+ */
+import type { MetricsPlatform } from "../../types/system-metrics.ts";
+
+export interface KillGuardContext {
+  platform: MetricsPlatform;
+  /** Validated-live PPM infra pids: server, parent/supervisor, edge forwarder,
+   *  every PPM-managed cloudflared. */
+  protectedPids: ReadonlySet<number>;
+  /** pid → ppid for this tick. Built once by the process collector. */
+  ppidOf: ReadonlyMap<number, number>;
+  /** pid → startedAt, so ancestor walks cannot follow a recycled parent. */
+  startedAtOf: ReadonlyMap<number, number>;
+}
+
+export interface KillGuardVerdict {
+  allowed: boolean;
+  reason?: string;
+}
+
+/** `taskkill /F` on the RPCSS/DcomLaunch `svchost` triggers CRITICAL_PROCESS_DIED;
+ *  `dwm` blanks the Win11 desktop. Task Manager refuses all of these too.
+ *  `explorer` is deliberately NOT here — it is killable, as in Task Manager. */
+export const WINDOWS_CRITICAL_NAMES: ReadonlySet<string> = new Set([
+  "system", "registry", "memory compression", "secure system", "smss", "csrss",
+  "wininit", "winlogon", "services", "lsass", "lsaiso", "svchost", "dwm",
+]);
+
+/** `sshd` is here because PPM is often driven from a phone against a remote
+ *  box: ending it locks the user out of the machine they are managing. */
+export const POSIX_CRITICAL_NAMES: ReadonlySet<string> = new Set([
+  "launchd", "kernel_task", "systemd", "init", "sshd",
+]);
+
+/**
+ * A parent cannot have started after its child. Unknown (0) start times are
+ * accepted — a missing value must not make a real chain invisible.
+ */
+function plausibleLink(parentStarted: number | undefined, childStarted: number | undefined): boolean {
+  if (!parentStarted || !childStarted) return true;
+  return parentStarted <= childStarted;
+}
+
+/** True when `target` is a strict ancestor of `pid` along plausible ppid links. */
+function isAncestorOf(target: number, pid: number, ctx: KillGuardContext): boolean {
+  const visited = new Set<number>([pid]);
+  let cur = pid;
+  while (true) {
+    const parent = ctx.ppidOf.get(cur);
+    if (parent === undefined || parent < 0 || visited.has(parent)) return false;
+    if (!plausibleLink(ctx.startedAtOf.get(parent), ctx.startedAtOf.get(cur))) return false;
+    if (parent === target) return true;
+    visited.add(parent);
+    cur = parent;
+  }
+}
+
+/** Every descendant of `root` along plausible ppid links, cycle-safe. */
+export function collectDescendants(root: number, ctx: Pick<KillGuardContext, "ppidOf" | "startedAtOf">): Set<number> {
+  const children = new Map<number, number[]>();
+  for (const [pid, ppid] of ctx.ppidOf) {
+    const list = children.get(ppid);
+    if (list) list.push(pid);
+    else children.set(ppid, [pid]);
+  }
+  const out = new Set<number>();
+  const queue = [root];
+  const visited = new Set<number>([root]);
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    for (const child of children.get(cur) ?? []) {
+      if (visited.has(child)) continue;
+      if (!plausibleLink(ctx.startedAtOf.get(cur), ctx.startedAtOf.get(child))) continue;
+      visited.add(child);
+      out.add(child);
+      queue.push(child);
+    }
+  }
+  return out;
+}
+
+export function checkKillAllowed(
+  target: { pid: number; name: string },
+  tree: boolean,
+  ctx: KillGuardContext,
+): KillGuardVerdict {
+  const { pid } = target;
+  const name = target.name.toLowerCase();
+  const refuse = (reason: string): KillGuardVerdict => ({ allowed: false, reason });
+
+  if (!Number.isInteger(pid) || pid <= 0) return refuse("Invalid PID");
+  if (ctx.protectedPids.has(pid)) return refuse(`${target.name} is a PPM process and cannot be ended`);
+
+  if (ctx.platform === "win32") {
+    if (pid === 4) return refuse("Cannot kill an OS kernel process");
+    if (WINDOWS_CRITICAL_NAMES.has(name)) return refuse(`${target.name} is an OS-critical process`);
+  } else {
+    if (pid <= 1) return refuse("Cannot kill init");
+    if (POSIX_CRITICAL_NAMES.has(name)) return refuse(`${target.name} is an OS-critical process`);
+  }
+
+  // Ending an ancestor of the PPM server kills the server while its orphaned
+  // grandchildren keep the inheritable listening socket — the zombie-port state.
+  for (const protectedPid of ctx.protectedPids) {
+    if (isAncestorOf(pid, protectedPid, ctx)) {
+      return refuse(`Ending ${target.name} would also end the PPM server`);
+    }
+  }
+
+  if (tree) {
+    const descendants = collectDescendants(pid, ctx);
+    for (const protectedPid of ctx.protectedPids) {
+      if (descendants.has(protectedPid)) return refuse("Ending this process tree would also end PPM");
+    }
+  }
+
+  return { allowed: true };
+}

package/src/services/system-metrics/kill-identity-resolver.ts

@@ -0,0 +1,72 @@
+/**
+ * Live re-query for a kill request. A pid is not an identity: Windows recycles
+ * pids fast enough that the `node` the user clicked two seconds ago can be
+ * `lsass` by the time the POST lands. The route therefore never authorises
+ * against the snapshot — it re-collects the process table (one round trip, the
+ * same per-OS source the tick uses), compares the client's `startedAt` claim
+ * with the live one, and hands the guard the FRESH name plus fresh ppid maps.
+ */
+import type { ProcessCollector, RawProcessRow } from "./process-collector-types.ts";
+
+export interface LiveProcessIdentity {
+  pid: number;
+  name: string;
+  startedAt: number;
+}
+
+/** macOS `ps` start times are 1 s resolution and other sources may be coarser. */
+export const IDENTITY_TOLERANCE_MS = 2000;
+
+/** An unknown start time (0) on either side cannot prove a mismatch. */
+export function identityMatches(claimedStartedAt: number, liveStartedAt: number): boolean {
+  if (!claimedStartedAt || !liveStartedAt) return true;
+  return Math.abs(claimedStartedAt - liveStartedAt) <= IDENTITY_TOLERANCE_MS;
+}
+
+export interface GuardMaps {
+  ppidOf: Map<number, number>;
+  startedAtOf: Map<number, number>;
+  byPid: Map<number, RawProcessRow>;
+  /** Rows that were refused because their pid was already present. */
+  warnings: string[];
+}
+
+/**
+ * A pid appears once in any real process table. A second row for the same pid
+ * can only be a forged line that slipped through the transport, so the FIRST
+ * row wins and the duplicate is refused — a forgery must never be able to
+ * overwrite the name the kill guard is about to trust.
+ */
+export function buildGuardMaps(rows: readonly RawProcessRow[]): GuardMaps {
+  const ppidOf = new Map<number, number>();
+  const startedAtOf = new Map<number, number>();
+  const byPid = new Map<number, RawProcessRow>();
+  const warnings: string[] = [];
+  for (const r of rows) {
+    if (byPid.has(r.pid)) {
+      warnings.push(`Duplicate row for PID ${r.pid} ignored (name "${r.name}")`);
+      continue;
+    }
+    byPid.set(r.pid, r);
+    ppidOf.set(r.pid, r.ppid);
+    startedAtOf.set(r.pid, r.startedAt);
+  }
+  return { ppidOf, startedAtOf, byPid, warnings };
+}
+
+export interface LiveResolution {
+  live: LiveProcessIdentity | null;
+  maps: GuardMaps;
+  warnings: string[];
+}
+
+export async function resolveLiveProcess(pid: number, collector: ProcessCollector): Promise<LiveResolution> {
+  const collection = await collector.collect();
+  const maps = buildGuardMaps(collection.rows);
+  const row = maps.byPid.get(pid);
+  return {
+    live: row ? { pid: row.pid, name: row.name, startedAt: row.startedAt } : null,
+    maps,
+    warnings: [...collection.warnings, ...maps.warnings],
+  };
+}

package/src/services/system-metrics/kill-request-handler.ts

@@ -0,0 +1,79 @@
+/**
+ * The kill decision chain, transport-free so it is testable without Hono:
+ *   parse → live re-query → identity check → guard on the FRESH name → execute.
+ * Authorising against the snapshot would authorise against data up to one tick
+ * old, and Windows recycles pids fast enough for that to matter.
+ */
+import type { KillProcessRequest, KillProcessResult, MetricsPlatform } from "../../types/system-metrics.ts";
+import { ok, err, type ApiResponse } from "../../types/api.ts";
+import type { ProcessCollector } from "./process-collector-types.ts";
+import { identityMatches, resolveLiveProcess } from "./kill-identity-resolver.ts";
+import { checkKillAllowed } from "./kill-guard.ts";
+import type { ProtectedPids } from "./ppm-protected-pids.ts";
+
+export interface KillHandlerDeps {
+  platform: MetricsPlatform;
+  collector: ProcessCollector;
+  resolveProtected: (isAlive: (pid: number) => boolean, nameOf: (pid: number) => string | undefined) => ProtectedPids;
+  execute: (pid: number, tree: boolean) => Promise<KillProcessResult>;
+  /** Audit line: pid + name + result ONLY. `~/.ppm/ppm.log`'s tail is served
+   *  unauthenticated by `/api/logs/recent`, so a command line must never land here. */
+  log: (line: string) => void;
+}
+
+export type KillStatus = 200 | 400 | 403 | 404 | 409 | 500;
+
+export interface KillOutcome {
+  status: KillStatus;
+  body: ApiResponse<KillProcessResult>;
+}
+
+export function parseKillRequest(body: unknown): KillProcessRequest | null {
+  if (!body || typeof body !== "object") return null;
+  const b = body as Record<string, unknown>;
+  const pid = b.pid;
+  const startedAt = b.startedAt;
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return null;
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt) || startedAt < 0) return null;
+  if (b.tree !== undefined && typeof b.tree !== "boolean") return null;
+  return { pid, startedAt, tree: b.tree === true };
+}
+
+export async function handleKillRequest(body: unknown, deps: KillHandlerDeps): Promise<KillOutcome> {
+  const req = parseKillRequest(body);
+  if (!req) return { status: 400, body: err("Body must be {pid: positive integer, startedAt: epoch ms, tree?: boolean}") };
+  const tree = req.tree === true;
+
+  const { live, maps } = await resolveLiveProcess(req.pid, deps.collector);
+  if (!live) return { status: 404, body: err(`PID ${req.pid} is no longer running`) };
+  if (!identityMatches(req.startedAt, live.startedAt)) {
+    return { status: 409, body: err(`PID ${req.pid} was recycled — refresh and try again`) };
+  }
+
+  const protectedPids = deps.resolveProtected(
+    (pid) => maps.byPid.has(pid),
+    (pid) => maps.byPid.get(pid)?.name.toLowerCase(),
+  );
+  const verdict = checkKillAllowed({ pid: live.pid, name: live.name }, tree, {
+    platform: deps.platform,
+    protectedPids: protectedPids.pids,
+    ppidOf: maps.ppidOf,
+    startedAtOf: maps.startedAtOf,
+  });
+  const prefix = `[SystemMetrics] kill pid=${live.pid} name=${live.name} tree=${tree}`;
+  if (!verdict.allowed) {
+    deps.log(`${prefix} → refused: ${verdict.reason}`);
+    return { status: 403, body: err(verdict.reason ?? "Refused") };
+  }
+
+  deps.log(`${prefix} → allowed`);
+  try {
+    const result = await deps.execute(live.pid, tree);
+    deps.log(`${prefix} → done (${result.method}, ${result.killed.length} signalled)`);
+    return { status: 200, body: ok(result) };
+  } catch (e) {
+    const message = (e as Error)?.message ?? String(e);
+    deps.log(`${prefix} → failed: ${message}`);
+    return { status: 500, body: err(`Failed to end PID ${live.pid}: ${message}`) };
+  }
+}

package/src/services/system-metrics/metrics-collector-lock.ts

@@ -0,0 +1,36 @@
+/**
+ * One holder at a time for the process collector. The PowerShell session takes
+ * a single request at a time, and a kill re-collects through the same collector
+ * the poll tick uses — so a kill waits for an in-flight tick, while a tick that
+ * arrives during a kill (or another tick) is simply skipped: metrics are lossy,
+ * a dropped poll is harmless, but two overlapping collections would either fail
+ * with "request already in flight" or double-consume the CPU delta baseline.
+ */
+export class CollectorLock {
+  private inflight: Promise<unknown> | null = null;
+
+  isHeld(): boolean {
+    return this.inflight !== null;
+  }
+
+  /** Run now if free, otherwise skip and resolve to `null`. */
+  async tryRun<T>(work: () => Promise<T>): Promise<T | null> {
+    if (this.inflight) return null;
+    return this.hold(work());
+  }
+
+  /** Wait for the current holder (however it ends), then run. */
+  async runExclusive<T>(work: () => Promise<T>): Promise<T> {
+    while (this.inflight) await this.inflight.catch(() => {});
+    return this.hold(work());
+  }
+
+  private async hold<T>(p: Promise<T>): Promise<T> {
+    this.inflight = p;
+    try {
+      return await p;
+    } finally {
+      this.inflight = null;
+    }
+  }
+}

package/src/services/system-metrics/metrics-poll-scheduler.ts

@@ -0,0 +1,83 @@
+/**
+ * Turns live subscriber demand into exactly one poll timer, plus the delayed
+ * child teardown when full-tier demand disappears. Timers follow demand:
+ * ≥1 full subscriber → full cadence; else ≥1 light → light cadence; else none.
+ */
+import type { MetricsTier } from "../../types/system-metrics.ts";
+
+export interface PollSchedulerOptions {
+  intervals: { full: number; light: number };
+  /** Grace before `onIdle` fires after the last full subscriber leaves, so a
+   *  window reopen does not pay the PowerShell bootstrap again. */
+  idleTeardownMs: number;
+  onTick: () => void;
+  /** Full-tier demand has been absent for the whole grace period. */
+  onIdle: () => void;
+  /** Full-tier collection is about to start for the first time. */
+  onFullStart: () => void;
+}
+
+export class PollScheduler {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private tier: MetricsTier | null = null;
+
+  constructor(private readonly opts: PollSchedulerOptions) {}
+
+  activeTier(): MetricsTier | null {
+    return this.tier;
+  }
+
+  /** Returns true when the active tier changed (so delta baselines may need a reset). */
+  reconcile(fullCount: number, lightCount: number): boolean {
+    const desired: MetricsTier | null = fullCount > 0 ? "full" : lightCount > 0 ? "light" : null;
+    if (desired === "full") this.clearIdle();
+    else if (this.tier === "full") this.armIdle();
+    if (desired === this.tier) return false;
+
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.tier = desired;
+    if (desired === "full") this.opts.onFullStart();
+    if (desired) {
+      this.timer = setInterval(this.opts.onTick, this.opts.intervals[desired]);
+      this.opts.onTick();
+    }
+    return true;
+  }
+
+  /** Re-arm the idle teardown after an out-of-band full collection (a kill). */
+  armIdle(): void {
+    this.clearIdle();
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      if (this.tier !== "full") this.opts.onIdle();
+    }, this.opts.idleTeardownMs);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.tier = null;
+    this.clearIdle();
+  }
+
+  private clearIdle(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+}
+
+const installedTeardowns = new WeakSet<() => void>();
+
+/** A hard exit must not leave a PowerShell child holding the server's
+ *  inheritable listening socket (the zombie-port state). The server's own
+ *  SIGTERM/SIGINT handler calls `process.exit`, which fires `exit` — so this
+ *  hook only tears down and never exits itself. Installed once per teardown fn. */
+export function installProcessExitHooks(teardown: () => void): void {
+  if (installedTeardowns.has(teardown)) return;
+  installedTeardowns.add(teardown);
+  process.on("exit", teardown);
+  process.on("SIGTERM", teardown);
+  process.on("SIGINT", teardown);
+}

package/src/services/system-metrics/metrics-subscriber-registry.ts

@@ -0,0 +1,85 @@
+/**
+ * SSE subscriber leases. A proxy in front of PPM (Cloudflare Tunnel) may keep
+ * the origin request alive after the browser left, so `cancel()` cannot be
+ * trusted: each subscriber holds a lease the client renews by pinging, and the
+ * server reaps silent ones. Without this, a phone that closed its tab would keep
+ * the PowerShell child running forever and burn one of the five stream slots.
+ */
+import type { MetricsSnapshot, MetricsTier } from "../../types/system-metrics.ts";
+
+export interface MetricsSubscriber {
+  sid: string;
+  tier: MetricsTier;
+  lastPingAt: number;
+  deliver: (snapshot: MetricsSnapshot) => void;
+  /** Called once when the server drops the subscriber (reap or explicit stop). */
+  close: () => void;
+}
+
+export const SID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** Accept only a short opaque id so a hostile query cannot bloat the map. */
+export function isValidSid(raw: string | undefined): raw is string {
+  return typeof raw === "string" && SID_PATTERN.test(raw);
+}
+
+export class SubscriberRegistry {
+  private readonly subs = new Map<string, MetricsSubscriber>();
+
+  add(sub: MetricsSubscriber): void {
+    this.subs.set(sub.sid, sub);
+  }
+
+  has(sid: string): boolean {
+    return this.subs.has(sid);
+  }
+
+  /** Remove and end the stream, so an explicit DELETE also closes the HTTP
+   *  response a proxy might otherwise hold open. `close` must be idempotent. */
+  remove(sid: string): boolean {
+    const s = this.subs.get(sid);
+    if (!s) return false;
+    this.subs.delete(sid);
+    try { s.close(); } catch { /* stream already gone */ }
+    return true;
+  }
+
+  ping(sid: string, now: number): boolean {
+    const s = this.subs.get(sid);
+    if (!s) return false;
+    s.lastPingAt = now;
+    return true;
+  }
+
+  /** Drop and close every lease silent for longer than `timeoutMs`. */
+  reap(now: number, timeoutMs: number): MetricsSubscriber[] {
+    const expired: MetricsSubscriber[] = [];
+    for (const s of this.subs.values()) {
+      if (now - s.lastPingAt > timeoutMs) expired.push(s);
+    }
+    for (const s of expired) {
+      this.subs.delete(s.sid);
+      try { s.close(); } catch { /* stream already gone */ }
+    }
+    return expired;
+  }
+
+  count(tier?: MetricsTier): number {
+    if (!tier) return this.subs.size;
+    let n = 0;
+    for (const s of this.subs.values()) if (s.tier === tier) n++;
+    return n;
+  }
+
+  list(tier: MetricsTier): MetricsSubscriber[] {
+    return [...this.subs.values()].filter((s) => s.tier === tier);
+  }
+
+  /** Close everything — server shutdown. */
+  clear(): void {
+    for (const s of this.subs.values()) {
+      try { s.close(); } catch { /* stream already gone */ }
+    }
+    this.subs.clear();
+  }
+}

package/src/services/system-metrics/powershell-session-bootstrap.ts

@@ -0,0 +1,48 @@
+/**
+ * The PowerShell REPL bootstrap and the real spawner for the long-lived session.
+ *
+ * Why not `-Command -` with stdin scripts: PS 5.1 executes stdin line by line,
+ * so a multi-line construct makes the child exit 0 silently with no stderr.
+ * Instead this bootstrap IS the loop: one request = one line
+ * `<id> <base64(UTF-16LE script)>`, one reply = everything up to a literal
+ * `__END_<id>__` line. Per-request ids mean a hostile command line containing a
+ * sentinel can desync at most the one in-flight reply.
+ */
+
+/** One `-Command` string. `try{} catch{}` must stay one logical statement — a
+ *  semicolon before `catch` is a parse error that kills the child at startup
+ *  with `MissingCatchOrFinally`. */
+export const POWERSHELL_BOOTSTRAP = [
+  "[Console]::OutputEncoding=[Text.Encoding]::UTF8",
+  "$ErrorActionPreference='Continue'",
+  "$in=[Console]::In",
+  "while($true){ $line=$in.ReadLine(); if($null -eq $line){break}; if($line -eq ''){continue}; " +
+    "$sp=$line.IndexOf(' '); $id=$line.Substring(0,$sp); " +
+    "$code=[Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($line.Substring($sp+1))); " +
+    "try { Invoke-Expression $code | Out-String -Width 1000000 -Stream | ForEach-Object { $_ } } catch { Write-Output ('__ERR__ ' + $_.Exception.Message) }; " +
+    "Write-Output ('__END_' + $id + '__') }",
+].join("; ");
+
+/** The minimal duplex surface the session needs, so tests can inject a fake. */
+export interface PsChild {
+  pid: number;
+  stdin: { write(data: string): unknown; flush?(): unknown };
+  stdout: ReadableStream<Uint8Array>;
+  stderr?: ReadableStream<Uint8Array> | null;
+  exited: Promise<number>;
+  kill(): void;
+}
+
+export type PsSpawner = () => PsChild;
+
+/** `-NoProfile`: a user profile can redefine cmdlets and poison the parse.
+ *  `-NonInteractive`: a prompt would wedge the pipe forever. */
+export const defaultPsSpawner: PsSpawner = () =>
+  Bun.spawn(["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", POWERSHELL_BOOTSTRAP], {
+    stdin: "pipe", stdout: "pipe", stderr: "pipe", windowsHide: true,
+  }) as unknown as PsChild;
+
+/** Encode one request line. The id is a small monotonic counter, never user input. */
+export function encodeRequestLine(id: string, script: string): string {
+  return `${id} ${Buffer.from(script, "utf16le").toString("base64")}\n`;
+}