@hienlh/ppm 0.18.14 → 0.18.15

package/src/services/remote-desktop/access-unit-assembler.ts

@@ -0,0 +1,90 @@
+/**
+ * Groups the raw NAL units from `NalSplitter` into WebCodecs-ready access units.
+ *
+ * `VideoDecoder` decodes one access unit (one frame) per `EncodedVideoChunk`, not one
+ * NAL — feeding SPS/PPS/slice as three separate chunks throws or corrupts decode. libx264
+ * (no B-frames, `-bf 0`) emits at most one slice NAL per frame, optionally preceded by
+ * SPS/PPS on a keyframe, so an AU boundary is simply "the next VCL NAL after we already
+ * buffered one" — everything non-VCL (SPS/PPS/AUD/SEI) that arrived first attaches to the
+ * AU it precedes.
+ */
+import { NalSplitter, nalType, isVclNal, NAL_TYPE_IDR, NAL_TYPE_SPS, NAL_TYPE_PPS } from "./nal-splitter.ts";
+
+export interface AccessUnit {
+  /** Annex-B encoded bytes (start codes + NAL payloads) — one `EncodedVideoChunk` worth. */
+  bytes: Uint8Array;
+  isKey: boolean;
+}
+
+const START_CODE = Uint8Array.of(0, 0, 0, 1);
+
+function encodeAnnexB(nals: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const n of nals) total += START_CODE.length + n.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const n of nals) {
+    out.set(START_CODE, offset);
+    offset += START_CODE.length;
+    out.set(n, offset);
+    offset += n.length;
+  }
+  return out;
+}
+
+export class AccessUnitAssembler {
+  private readonly splitter = new NalSplitter();
+  private pending: Uint8Array[] = [];
+  private pendingHasVcl = false;
+  private sps: Uint8Array | null = null;
+  private pps: Uint8Array | null = null;
+
+  /** Feed a raw ffmpeg stdout chunk; returns zero or more completed access units. */
+  push(chunk: Uint8Array): AccessUnit[] {
+    const aus: AccessUnit[] = [];
+    for (const nal of this.splitter.push(chunk)) {
+      const type = nalType(nal);
+      if (type === NAL_TYPE_SPS) this.sps = nal;
+      else if (type === NAL_TYPE_PPS) this.pps = nal;
+
+      const vcl = isVclNal(nal);
+      if (vcl && this.pendingHasVcl) {
+        const au = this.flush();
+        if (au) aus.push(au);
+      }
+      this.pending.push(nal);
+      if (vcl) this.pendingHasVcl = true;
+    }
+    return aus;
+  }
+
+  /** SPS bytes seen so far (NAL header byte included) — used to derive the avc1 codec
+   *  string. Null until the encoder has emitted its first keyframe. */
+  cachedSps(): Uint8Array | null {
+    return this.sps;
+  }
+
+  private flush(): AccessUnit | null {
+    if (this.pending.length === 0) {
+      this.pendingHasVcl = false;
+      return null;
+    }
+    let nals = this.pending;
+    const isKey = nals.some((n) => nalType(n) === NAL_TYPE_IDR);
+    if (isKey) {
+      // A late-joining client (or a client that missed the very first AU) needs SPS+PPS
+      // concatenated into the same key chunk it decodes — three separate chunks is not
+      // decodable Annex-B input for WebCodecs. Normally libx264 already includes them; this
+      // is a defensive backfill from the cache, not the common path.
+      const hasSps = nals.some((n) => nalType(n) === NAL_TYPE_SPS);
+      const hasPps = nals.some((n) => nalType(n) === NAL_TYPE_PPS);
+      const prefix: Uint8Array[] = [];
+      if (!hasSps && this.sps) prefix.push(this.sps);
+      if (!hasPps && this.pps) prefix.push(this.pps);
+      if (prefix.length > 0) nals = [...prefix, ...nals];
+    }
+    this.pending = [];
+    this.pendingHasVcl = false;
+    return { bytes: encodeAnnexB(nals), isKey };
+  }
+}

package/src/services/remote-desktop/avc1-codec-string.ts

@@ -0,0 +1,18 @@
+/**
+ * Derive the WebCodecs `avc1.PPCCLL` codec string from a real SPS NAL rather than
+ * guessing. `encoderArgs()` in `ffmpeg-capabilities.ts` sets no `-profile`/`-level`, so the
+ * actual encoded profile/level is encoder-default and unknown until the bitstream exists —
+ * a hardcoded guess can mismatch and make `VideoDecoder.configure()` throw or refuse.
+ *
+ * SPS layout (after the 1-byte NAL header at index 0): profile_idc, then the
+ * constraint-flags/reserved byte, then level_idc — always the first three bytes of the
+ * RBSP, unaffected by emulation-prevention bytes (those only appear deeper in the SPS).
+ */
+export function avc1CodecString(sps: Uint8Array): string | null {
+  if (sps.length < 4) return null;
+  const profileIdc = sps[1]!;
+  const constraintFlags = sps[2]!;
+  const levelIdc = sps[3]!;
+  const hex = (n: number) => n.toString(16).padStart(2, "0");
+  return `avc1.${hex(profileIdc)}${hex(constraintFlags)}${hex(levelIdc)}`;
+}

package/src/services/remote-desktop/nal-splitter.ts

@@ -0,0 +1,100 @@
+/**
+ * Incremental Annex-B start-code splitter.
+ *
+ * ffmpeg's `-f h264` stdout is a raw Annex-B byte stream: NAL units separated by
+ * `00 00 01` or `00 00 00 01` start codes, with no framing that respects our read
+ * chunk boundaries. A NAL can straddle two `stdout` reads, so this holds the tail
+ * of the last incomplete NAL across calls to `push()` rather than assuming a full
+ * NAL always arrives in one chunk.
+ */
+
+/** NAL unit types relevant to access-unit assembly (ITU-T H.264 Table 7-1). */
+export const NAL_TYPE_SLICE_NON_IDR = 1;
+export const NAL_TYPE_IDR = 5;
+export const NAL_TYPE_SPS = 7;
+export const NAL_TYPE_PPS = 8;
+
+/** Low 5 bits of the NAL header byte (the unit's first byte) is `nal_unit_type`. */
+export function nalType(nal: Uint8Array): number {
+  return (nal[0] ?? 0) & 0x1f;
+}
+
+/** A slice NAL starts a new access unit; SPS/PPS/AUD/SEI attach to whichever AU follows them. */
+export function isVclNal(nal: Uint8Array): boolean {
+  const t = nalType(nal);
+  return t === NAL_TYPE_SLICE_NON_IDR || t === NAL_TYPE_IDR;
+}
+
+/** `Bun.spawn` stdout chunks type as `Uint8Array<ArrayBufferLike>` (could in principle back
+ *  onto a SharedArrayBuffer), while `new Uint8Array(n)` types as the narrower
+ *  `Uint8Array<ArrayBuffer>` — pin everything here to the wider type so a plain chunk and our
+ *  own freshly-allocated buffers can always mix without a type error. */
+export type Bytes = Uint8Array<ArrayBufferLike>;
+
+function concat(a: Bytes, b: Bytes): Bytes {
+  if (a.length === 0) return b;
+  if (b.length === 0) return a;
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/** Index of the next `00 00 01` marker at or after `from`, or -1. This always finds the
+ *  *last* 3 bytes of a start code — a 4-byte `00 00 00 01` form has its 3-byte suffix match
+ *  here too (at index+1), and H.264 emulation prevention guarantees `00 00 01`/`00 00 00`
+ *  never occurs inside real RBSP payload data, so there is no false-positive risk scanning
+ *  straight through NAL bodies. */
+function findStartCode(buf: Bytes, from: number): number {
+  for (let i = from; i + 2 < buf.length; i++) {
+    if (buf[i] === 0 && buf[i + 1] === 0 && buf[i + 2] === 1) return i;
+  }
+  return -1;
+}
+
+/** Bytes to skip past a marker found by `findStartCode` to reach the payload — always 3
+ *  (the marker itself), regardless of how many extra leading zero bytes preceded it. */
+const MARKER_LEN = 3;
+
+/** Guard against an unbounded buffer if ffmpeg ever emits a byte stream with no start
+ *  code at all (would indicate a broken pipe/format, not a real Annex-B stream). */
+const MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+
+export class NalSplitter {
+  private buffer: Bytes = new Uint8Array(0);
+
+  /** Feed a raw stdout chunk; returns zero or more complete NAL payloads (start code
+   *  stripped). Incomplete trailing bytes are retained for the next call. */
+  push(chunk: Bytes): Bytes[] {
+    this.buffer = concat(this.buffer, chunk);
+    const nals: Bytes[] = [];
+
+    let start = findStartCode(this.buffer, 0);
+    if (start === -1) {
+      if (this.buffer.length > MAX_BUFFER_BYTES) this.buffer = new Uint8Array(0);
+      return nals;
+    }
+    // Drop any garbage before the first start code (should not happen with a clean
+    // ffmpeg pipe, but a partial NAL from before this splitter attached must not corrupt
+    // the first parsed unit).
+    for (;;) {
+      const nextStart = findStartCode(this.buffer, start + MARKER_LEN);
+      if (nextStart === -1) {
+        this.buffer = this.buffer.slice(start);
+        break;
+      }
+      // `nextStart` only marks the *last* 3 bytes of the following start code — a 4-byte
+      // `00 00 00 01` form leaves its leading zero sitting right before `nextStart`, which
+      // would otherwise get appended to this NAL's payload as a spurious trailing byte.
+      // Trim any such zero bytes back to the real payload end (standard Annex-B handling of
+      // `leading_zero_8bits`/`trailing_zero_8bits`).
+      let payloadEnd = nextStart;
+      const payloadStart = start + MARKER_LEN;
+      while (payloadEnd > payloadStart && this.buffer[payloadEnd - 1] === 0) payloadEnd--;
+      const payload = this.buffer.slice(payloadStart, payloadEnd);
+      if (payload.length > 0) nals.push(payload);
+      start = nextStart;
+    }
+    return nals;
+  }
+}

package/src/services/remote-desktop/remote-desktop-capture.ts

@@ -0,0 +1,120 @@
+/**
+ * Spawn ffmpeg (`gdigrab` → H.264 Annex-B on `pipe:1`) and turn its stdout into access units.
+ *
+ * Teardown is `proc.kill()` only — never `reader.cancel()`, never `for await (chunk of
+ * proc.stdout) { ... break }`. Both of those cancel the underlying stream reader, which
+ * segfaults Bun 1.3.x on Windows the instant a consumer goes away (see
+ * `transcode-stream.ts:130-148` and `tests/integration/transcode-stream-client-disconnect.test.ts`
+ * — that guard targets a `Response` body; the WS rewrite here re-creates the same trap one
+ * layer down if the pump loop is written as `for await`). `stop()` only calls `proc.kill()`;
+ * the in-flight `reader.read()` then resolves with `done: true` and the pump loop exits on
+ * its own — it is never cancelled from outside.
+ */
+import { getFfmpegCapabilities } from "../media-transcode/ffmpeg-capabilities.ts";
+import { captureEncoderArgs, CAPTURE_FRAMERATE } from "./remote-desktop-encoder-args.ts";
+import { AccessUnitAssembler, type AccessUnit } from "./access-unit-assembler.ts";
+
+export class CaptureUnavailableError extends Error {
+  constructor(msg = "ffmpeg is not installed (gdigrab capture requires it)") {
+    super(msg);
+    this.name = "CaptureUnavailableError";
+  }
+}
+
+/** Build the gdigrab argv; pure so it can be asserted on without spawning a process.
+ *  `-fflags nobuffer -flags low_delay` + `-flush_packets 1` stop ffmpeg from holding frames in
+ *  its demux/mux buffers before emitting — on a fast/LAN transport that buffering is a big slice
+ *  of the felt lag. `encoder` selects the H.264 encoder args (hardware NVENC/QSV/AMF when the
+ *  capability probe found one, else libx264). */
+export function buildCaptureArgs(ffmpeg: string, encoder: string = "libx264"): string[] {
+  return [
+    ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
+    "-fflags", "nobuffer", "-flags", "low_delay",
+    "-f", "gdigrab", "-framerate", String(CAPTURE_FRAMERATE), "-i", "desktop",
+    "-vf", "scale=-2:720",
+    ...captureEncoderArgs(encoder),
+    "-flush_packets", "1",
+    "-f", "h264", "pipe:1",
+  ];
+}
+
+export interface CaptureHandle {
+  /** SPS bytes cached from the stream (for the avc1 codec string), null before the encoder's
+   *  first keyframe has been parsed. */
+  cachedSps(): Uint8Array | null;
+  /** Kill ffmpeg. Idempotent, safe to call from multiple teardown paths. */
+  stop(): void;
+  /** True once `stop()` has run or the process exited on its own. */
+  isStopped(): boolean;
+}
+
+export interface StartCaptureOptions {
+  onAccessUnit: (au: AccessUnit) => void;
+  /** Called once the process exits, whether via `stop()` or on its own (crash/killed
+   *  externally) — lets the session registry clean up without polling. `reason` is a short
+   *  stderr tail, present only when ffmpeg died on its own (e.g. gdigrab access denied on a
+   *  disconnected session) so the caller can surface *why* to the client instead of a bare
+   *  disconnect. */
+  onExit?: (code: number | null, reason?: string) => void;
+}
+
+/** Start gdigrab capture. Rejects immediately if ffmpeg is not on PATH. */
+export async function startCapture(opts: StartCaptureOptions): Promise<CaptureHandle> {
+  const caps = await getFfmpegCapabilities();
+  if (!caps.ffmpeg) throw new CaptureUnavailableError();
+
+  const proc = Bun.spawn(buildCaptureArgs(caps.ffmpeg, caps.encoder ?? "libx264"), {
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (!proc.killed) proc.kill();
+  };
+
+  // Drain stderr so ffmpeg never blocks on a full pipe; keep a short tail for diagnostics.
+  const stderrTail = new Response(proc.stderr).text().catch(() => "");
+  proc.exited.then(async (code) => {
+    // Read `stopped` BEFORE overwriting it: this is the only reliable "did WE ask ffmpeg to
+    // die" signal. `proc.killed` is NOT reliable for that — Bun sets it `true` even when
+    // ffmpeg exits on its own with a nonzero code (verified: gdigrab "access denied" on a
+    // disconnected session exits with `killed: true` despite `stop()` never having been
+    // called), which previously suppressed this warning — and any client-facing error —
+    // for exactly the crash this exists to report.
+    const diedOnItsOwn = !stopped;
+    stopped = true;
+    let reason: string | undefined;
+    if (diedOnItsOwn && code !== 0 && code !== null) {
+      reason = (await stderrTail).trim().split("\n").slice(-3).join(" | ");
+      console.warn(`[remote-desktop] ffmpeg exited ${code}: ${reason}`);
+    }
+    opts.onExit?.(code, reason);
+  });
+
+  const assembler = new AccessUnitAssembler();
+
+  // Manual pull loop — the only safe way to drain this stdout (see file header). Runs
+  // detached from the caller; it terminates itself once `proc.kill()` resolves the pending
+  // read with `done: true`, never via an external cancel.
+  const reader = proc.stdout.getReader();
+  (async () => {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (!value) continue;
+      for (const au of assembler.push(value)) opts.onAccessUnit(au);
+    }
+  })().catch((e) => {
+    console.error(`[remote-desktop] capture pump failed: ${(e as Error).message}`);
+  });
+
+  return {
+    cachedSps: () => assembler.cachedSps(),
+    stop,
+    isStopped: () => stopped,
+  };
+}

package/src/services/remote-desktop/remote-desktop-encoder-args.ts

@@ -0,0 +1,42 @@
+/**
+ * Capture-tuned libx264 args — deliberately NOT `encoderArgs()` from `ffmpeg-capabilities.ts`.
+ * That table is tuned for "watch a file" (nvenc VBR, libx264 `-crf 23 -maxrate 8M -bufsize
+ * 16M`), which fights a real-time capture: large bufsize/VBR inflates latency spikes exactly
+ * where `-tune zerolatency` is trying to remove them.
+ *
+ * libx264 is forced (never the hardware picks from `ffmpeg-capabilities.ts`) so profile/level
+ * behavior is deterministic across machines — the actual codec string is still derived from
+ * the real SPS bytes at runtime (`avc1-codec-string.ts`), this just keeps that derivation
+ * predictable during development.
+ */
+
+/** 30fps + a 1s keyframe interval (30 frames): smoother than 15fps and bounds how long a
+ *  dropped/late-joining client waits to resync (see WS backpressure handling). */
+export const CAPTURE_FRAMERATE = 30;
+export const CAPTURE_GOP_FRAMES = 30;
+
+/** ffmpeg output args for the H.264 encode step (goes after `-i desktop -vf ...`).
+ *  Prefers hardware NVENC (verified to work even under an RDP session on this class of GPU) —
+ *  hardware encode adds ~5–15ms vs 30–100ms for libx264, the dominant slice of the felt lag on
+ *  a fast/LAN transport. Falls back to a low-latency libx264 profile when no hardware H.264
+ *  encoder is available. The avc1 codec string is derived from the real SPS at runtime, so the
+ *  encoder's actual profile/level is handled regardless of which branch runs. */
+export function captureEncoderArgs(encoder: string = "libx264"): string[] {
+  const common = ["-b:v", "6M", "-maxrate", "6M", "-g", String(CAPTURE_GOP_FRAMES), "-bf", "0", "-pix_fmt", "yuv420p"];
+  switch (encoder) {
+    case "h264_nvenc":
+      // p2 + `-tune ll` (low latency), CBR, no frame reordering, minimal output delay/VBV.
+      return ["-c:v", "h264_nvenc", "-preset", "p2", "-tune", "ll", "-rc", "cbr",
+        "-zerolatency", "1", "-delay", "0", "-bufsize", "512k", ...common];
+    case "h264_qsv":
+      return ["-c:v", "h264_qsv", "-preset", "veryfast", "-low_power", "1", "-bufsize", "512k", ...common];
+    case "h264_amf":
+      return ["-c:v", "h264_amf", "-quality", "speed", "-rc", "cbr", "-bufsize", "512k", ...common];
+    default:
+      // libx264 low-latency. `-tune zerolatency` enables sliced-threads (multi-slice NALs);
+      // access-unit-assembler.ts assumes one slice/frame, so force it back with sliced-threads=0.
+      return ["-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency",
+        "-profile:v", "main", "-level", "4.0", "-x264-params", "sliced-threads=0:slices=1",
+        "-bufsize", "1M", ...common];
+  }
+}

package/src/services/remote-desktop/remote-desktop-flag.ts

@@ -0,0 +1,10 @@
+/**
+ * Feature flag gate. A live video+input channel to the host must never be reachable just
+ * because the code shipped — default OFF until phase-07 hardening (host-approval prompt,
+ * signed input path) lands. Every entry point (REST routes, WS upgrade) checks this
+ * independently rather than trusting a single call site.
+ */
+export function isRemoteDesktopEnabled(): boolean {
+  const v = process.env.REMOTE_DESKTOP_ENABLED;
+  return v === "1" || v === "true";
+}

package/src/services/remote-desktop/remote-desktop-input.ts

@@ -0,0 +1,217 @@
+/**
+ * Mouse/keyboard injection via Bun FFI straight into `user32.dll` `SendInput` — no separate
+ * helper process (drops the Rust-binary build step + unsigned-exe/SmartScreen risk the phase
+ * plan flagged for a bundled injector; phase 02's SYSTEM-session helper is a different
+ * process/token anyway, so nothing here is meant to be reused as-is).
+ *
+ * Normal desktop only, current interactive session, no SYSTEM/UAC/lock-screen support.
+ *
+ * `bun:ffi` is only ever `import()`-ed and `dlopen`-ed lazily from inside `loadUser32()`, so
+ * merely importing this module (routing, types) on Linux/macOS test runners never touches
+ * `user32.dll`.
+ */
+import { codeToVk, MODIFIER_VK_CODES } from "./remote-desktop-vk-map.ts";
+
+export class RemoteInputUnavailableError extends Error {
+  constructor(msg = "Remote input injection is only available on Windows") {
+    super(msg);
+    this.name = "RemoteInputUnavailableError";
+  }
+}
+
+const INPUT_MOUSE = 0;
+const INPUT_KEYBOARD = 1;
+const MOUSEEVENTF_MOVE = 0x0001;
+const MOUSEEVENTF_LEFTDOWN = 0x0002;
+const MOUSEEVENTF_LEFTUP = 0x0004;
+const MOUSEEVENTF_RIGHTDOWN = 0x0008;
+const MOUSEEVENTF_RIGHTUP = 0x0010;
+const MOUSEEVENTF_ABSOLUTE = 0x8000;
+const MOUSEEVENTF_VIRTUALDESK = 0x4000;
+const MOUSEEVENTF_WHEEL = 0x0800;
+/** One notch of a real mouse wheel — `mouseData` for `MOUSEEVENTF_WHEEL` is a signed multiple
+ *  of this constant, not a raw pixel delta. */
+const WHEEL_DELTA = 120;
+const KEYEVENTF_KEYUP = 0x0002;
+/** `((DPI_AWARENESS_CONTEXT)-4)` — PER_MONITOR_AWARE_V2. Not a real pointer; the x64 ABI
+ *  passes it in the same register/slot as a pointer arg would, bit pattern only. */
+const DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = -4n;
+/** Each `INPUT` struct is 40 bytes on x64 (8-byte `type` slot + 32-byte union). */
+const INPUT_STRUCT_SIZE = 40;
+/** Desktop access rights for input injection. `SendInput` silently no-ops when the calling
+ *  thread is not attached to the *input* desktop; attaching needs the READ/WRITE/SWITCH rights
+ *  plus JOURNALPLAYBACK so the desktop accepts injected input. These MUST be the real DESKTOP_*
+ *  bit values — an invalid mask (e.g. an out-of-range bit) makes `OpenInputDesktop` return NULL
+ *  and the attach silently fails, leaving SendInput pointed at the wrong desktop. */
+const DESKTOP_READOBJECTS = 0x0001;
+const DESKTOP_JOURNALPLAYBACK = 0x0020;
+const DESKTOP_WRITEOBJECTS = 0x0080;
+const DESKTOP_SWITCHDESKTOP = 0x0100;
+const INPUT_DESKTOP_ACCESS =
+  DESKTOP_READOBJECTS | DESKTOP_JOURNALPLAYBACK | DESKTOP_WRITEOBJECTS | DESKTOP_SWITCHDESKTOP; // 0x1A1
+
+/** WINSTA_ALL_ACCESS — enough to open the interactive window station and make it this process's
+ *  station so its input desktop becomes reachable. */
+const WINSTA_ALL_ACCESS = 0x37f;
+
+type FfiModule = typeof import("bun:ffi");
+type User32Symbols = {
+  SendInput: (count: number, ptr: number | bigint, size: number) => number;
+  SetProcessDpiAwarenessContext: (ctx: bigint) => boolean;
+  OpenInputDesktop: (flags: number, inherit: boolean, access: number) => number | bigint;
+  SetThreadDesktop: (hdesk: number | bigint) => boolean;
+  CloseDesktop: (hdesk: number | bigint) => boolean;
+  OpenWindowStationW: (name: number | bigint, inherit: boolean, access: number) => number | bigint;
+  SetProcessWindowStation: (hwinsta: number | bigint) => boolean;
+};
+
+let ffiModule: FfiModule | null = null;
+let user32: User32Symbols | null = null;
+let dpiAwarenessAttempted = false;
+
+async function loadUser32(): Promise<{ ffi: FfiModule; lib: User32Symbols }> {
+  if (process.platform !== "win32") throw new RemoteInputUnavailableError();
+  if (!ffiModule) ffiModule = await import("bun:ffi");
+  const { dlopen, FFIType } = ffiModule;
+  if (!user32) {
+    user32 = dlopen("user32.dll", {
+      SendInput: { args: [FFIType.u32, FFIType.ptr, FFIType.i32], returns: FFIType.u32 },
+      SetProcessDpiAwarenessContext: { args: [FFIType.i64], returns: FFIType.bool },
+      OpenInputDesktop: { args: [FFIType.u32, FFIType.bool, FFIType.u32], returns: FFIType.ptr },
+      SetThreadDesktop: { args: [FFIType.ptr], returns: FFIType.bool },
+      CloseDesktop: { args: [FFIType.ptr], returns: FFIType.bool },
+      OpenWindowStationW: { args: [FFIType.ptr, FFIType.bool, FFIType.u32], returns: FFIType.ptr },
+      SetProcessWindowStation: { args: [FFIType.ptr], returns: FFIType.bool },
+    }).symbols as unknown as User32Symbols;
+  }
+  if (!dpiAwarenessAttempted) {
+    dpiAwarenessAttempted = true;
+    // A second call to this in the same process returns E_ACCESSDENIED — swallow it, it just
+    // means something else (or a previous session) already set it.
+    try { user32.SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2); } catch { /* already set */ }
+  }
+  return { ffi: ffiModule, lib: user32 };
+}
+
+function writeMouseInput(dv: DataView, offset: number, xAbs: number, yAbs: number, flags: number, mouseData = 0): void {
+  dv.setUint32(offset, INPUT_MOUSE, true);
+  dv.setInt32(offset + 8, xAbs, true);
+  dv.setInt32(offset + 12, yAbs, true);
+  dv.setInt32(offset + 16, mouseData, true); // wheel delta for MOUSEEVENTF_WHEEL, unused otherwise
+  dv.setUint32(offset + 20, flags >>> 0, true);
+  dv.setUint32(offset + 24, 0, true); // time: 0 lets the system supply it
+}
+
+function writeKeyInput(dv: DataView, offset: number, vk: number, keyUp: boolean): void {
+  dv.setUint32(offset, INPUT_KEYBOARD, true);
+  dv.setUint16(offset + 8, vk, true);
+  dv.setUint16(offset + 10, 0, true); // wScan — unused, we inject by VK not scan code
+  dv.setUint32(offset + 12, keyUp ? KEYEVENTF_KEYUP : 0, true);
+  dv.setUint32(offset + 16, 0, true); // time
+}
+
+/** Handle of the desktop this thread is currently attached to, so we can close the previous one
+ *  when the active input desktop changes (lock/unlock/UAC switches it). One handle in flight. */
+let attachedDesktop: number | bigint | null = null;
+
+/** Attach the calling thread to the *current* input desktop before injecting. Re-run every send
+ *  because the input desktop changes on lock/unlock; `CreateProcessAsUser`/process start only
+ *  fixes the initial desktop, not later switches. Best-effort: on failure we still try SendInput
+ *  (it just no-ops), and log once rather than per-event spam. */
+/** Attach the PROCESS to the interactive window station ("winsta0") once, so its input desktop
+ *  is reachable. Without this, a PPM process launched from a non-interactive station (a service,
+ *  or some spawners) can't OpenInputDesktop at all — SendInput then goes nowhere. No-op when the
+ *  process is already on winsta0 (the normal case for PPM started inside the user's session). */
+let stationEnsured = false;
+function ensureInteractiveStation(ffi: FfiModule, lib: User32Symbols): void {
+  if (stationEnsured) return;
+  stationEnsured = true;
+  const name = "winsta0";
+  const wide = new Uint16Array(name.length + 1);
+  for (let i = 0; i < name.length; i++) wide[i] = name.charCodeAt(i);
+  const hwinsta = lib.OpenWindowStationW(ffi.ptr(wide), false, WINSTA_ALL_ACCESS);
+  if (!hwinsta) return; // already on it, or no access — OpenInputDesktop below will tell us
+  lib.SetProcessWindowStation(hwinsta);
+}
+
+function attachToInputDesktop(ffi: FfiModule, lib: User32Symbols): void {
+  ensureInteractiveStation(ffi, lib);
+  const hdesk = lib.OpenInputDesktop(0, false, INPUT_DESKTOP_ACCESS);
+  if (!hdesk) return; // couldn't open the input desktop (e.g. secure/lock desktop); leave thread as-is
+  const ok = lib.SetThreadDesktop(hdesk);
+  if (ok) {
+    if (attachedDesktop && attachedDesktop !== hdesk) {
+      try { lib.CloseDesktop(attachedDesktop); } catch { /* ignore */ }
+    }
+    attachedDesktop = hdesk;
+  } else {
+    // SetThreadDesktop fails if this thread owns windows/hooks — shouldn't for the server thread.
+    try { lib.CloseDesktop(hdesk); } catch { /* ignore */ }
+  }
+}
+
+async function sendRaw(buf: Uint8Array, count: number): Promise<void> {
+  const { ffi, lib } = await loadUser32();
+  attachToInputDesktop(ffi, lib);
+  const sent = lib.SendInput(count, ffi.ptr(buf), INPUT_STRUCT_SIZE);
+  if (sent !== count) console.warn(`[remote-desktop] SendInput accepted ${sent}/${count} events`);
+}
+
+/** Move the cursor and, if this is a click, press/release the button — one absolute move
+ *  per call so the button acts at the position the client actually clicked. `xFrac`/`yFrac`
+ *  are 0..1 fractions of the capture (client already dropped devicePixelRatio; only the
+ *  canvas-relative fraction is meaningful for host coordinates). */
+export async function injectPointer(
+  xFrac: number,
+  yFrac: number,
+  button: "left" | "right" | null,
+  down: boolean | null,
+): Promise<void> {
+  const xAbs = Math.round(Math.min(Math.max(xFrac, 0), 1) * 65535);
+  const yAbs = Math.round(Math.min(Math.max(yFrac, 0), 1) * 65535);
+  let flags = MOUSEEVENTF_MOVE | MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_VIRTUALDESK;
+  if (button === "left") flags |= down ? MOUSEEVENTF_LEFTDOWN : MOUSEEVENTF_LEFTUP;
+  else if (button === "right") flags |= down ? MOUSEEVENTF_RIGHTDOWN : MOUSEEVENTF_RIGHTUP;
+
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE);
+  writeMouseInput(new DataView(buf.buffer), 0, xAbs, yAbs, flags);
+  await sendRaw(buf, 1);
+}
+
+/** Scroll the wheel. `deltaY` is in `WHEEL_DELTA` (120) units — positive rotates the wheel
+ *  forward (scrolls up/away from the user), negative rotates backward (scrolls down). The
+ *  client accumulates raw two-finger-drag pixels into this unit before sending, so this layer
+ *  stays a dumb relay: round + clamp to a safe i16 range so a runaway client value can't wrap
+ *  into a huge or negative-looking mouseData field. */
+export async function injectWheel(deltaY: number): Promise<void> {
+  const clamped = Math.max(-32768, Math.min(32767, Math.round(deltaY)));
+  if (clamped === 0) return;
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE);
+  writeMouseInput(new DataView(buf.buffer), 0, 0, 0, MOUSEEVENTF_WHEEL, clamped);
+  await sendRaw(buf, 1);
+}
+
+/** Send a keydown/keyup by physical key code. Returns false for an unmapped code (caller
+ *  should just drop it rather than injecting a wrong key). */
+export async function injectKey(code: string, down: boolean): Promise<boolean> {
+  const vk = codeToVk(code);
+  if (vk === null) return false;
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE);
+  writeKeyInput(new DataView(buf.buffer), 0, vk, !down);
+  await sendRaw(buf, 1);
+  return true;
+}
+
+/** Force keyup for every modifier VK, regardless of tracked state — the backstop for a lost
+ *  keyup (blur, WS drop) leaving Shift/Ctrl/Alt/Win logically held on the host. */
+export async function releaseAllModifiers(): Promise<void> {
+  if (process.platform !== "win32") return;
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE * MODIFIER_VK_CODES.length);
+  const dv = new DataView(buf.buffer);
+  MODIFIER_VK_CODES.forEach((vk, i) => writeKeyInput(dv, i * INPUT_STRUCT_SIZE, vk, true));
+  try { await sendRaw(buf, MODIFIER_VK_CODES.length); } catch { /* best-effort */ }
+}
+
+export function isInputAvailable(): boolean {
+  return process.platform === "win32";
+}

package/src/services/remote-desktop/remote-desktop-nonce.ts

@@ -0,0 +1,38 @@
+/**
+ * Single-use, short-TTL connection nonce — mirrors `download-token.service.ts`'s
+ * consume-once pattern.
+ *
+ * The PPM static bearer token already travels as `?token=` on every WS upgrade
+ * (`isWsUpgradeAuthorized`, `src/server/index.ts`) and proves nothing beyond "holds the one
+ * reusable app token" — it is not a real per-session grant. `POST /api/remote-desktop/session`
+ * mints one of these after re-checking `auth.enabled`; the client then presents it via the WS
+ * subprotocol header (never the query string) and it is consumed exactly once, at upgrade
+ * time, in `src/server/index.ts`.
+ */
+import { randomUUIDv7 } from "bun";
+
+const TTL_MS = 30_000;
+const nonces = new Map<string, number>();
+
+/** Mint a nonce; caller must have already verified auth is enabled + a valid request. */
+export function mintRemoteDesktopNonce(): string {
+  const token = randomUUIDv7();
+  nonces.set(token, Date.now());
+  cleanup();
+  return token;
+}
+
+/** Validate + consume. Returns false for missing/expired/already-used nonces. */
+export function consumeRemoteDesktopNonce(token: string): boolean {
+  const mintedAt = nonces.get(token);
+  if (mintedAt === undefined) return false;
+  nonces.delete(token);
+  return Date.now() - mintedAt <= TTL_MS;
+}
+
+function cleanup(): void {
+  const now = Date.now();
+  for (const [token, mintedAt] of nonces) {
+    if (now - mintedAt > TTL_MS) nonces.delete(token);
+  }
+}