@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/lib/windows-elevation.ts

@@ -253,12 +253,15 @@ export const OCX_ELEVATED_UAC_CANCELLED = 1223;
 /**
  * The elevated process could not read a staged payload (#4692).
  *
- * `hardenSecretPath` grants the staging account and strips inheritance, so a split-token
- * elevation of the same user reads the file and an elevation answered with a DIFFERENT
- * administrator's credentials does not. The elevated side cannot explain that itself: it
- * runs hidden, so its stderr goes nowhere and only the exit code survives the boundary.
- * Without a code of its own the operator would be told "exit code 1" for a cause that
- * names its own remedy — the same undiagnosable failure this change set exists to remove.
+ * The staged ACL grants the staging account plus read for SYSTEM and
+ * BUILTIN\Administrators (#4779), so both a split-token elevation and an
+ * over-the-shoulder one answered with a different administrator's credentials
+ * can open it. A residual read failure means the hardening did not take effect
+ * or the payload was replaced. The elevated side cannot explain that itself: it
+ * runs hidden, so its stderr goes nowhere and only the exit code survives the
+ * boundary. Without a code of its own the operator would be told "exit code 1"
+ * for a cause that names its own remedy — the same undiagnosable failure this
+ * change set exists to remove.
  *
  * Deliberately outside OCX_ELEVATED_PROTOCOL_CODES: that list is the create-and-run
  * transaction's alphabet, and this code belongs to the registration path.
@@ -662,14 +665,17 @@ export function runWindowsElevated(file: string, args: string[]): Promise<number
 /**
  * A task definition staged for the elevated process.
  *
- * The bytes live in a freshly created, ACL-hardened private directory, and the digest is
- * taken over exactly those bytes by the caller that validated them. The elevated script
- * reads the file once, hashes what it read, and refuses unless the digest matches, so a
- * pathname is no longer a promise about content — it is a claim the receiver checks.
+ * Before elevation, the launcher pins the file and every ancestor with non-reparse
+ * handles: payload files deny write/delete sharing, ancestor directories deny delete
+ * sharing only (writes inside them stay possible so the stage can be populated).
+ * The elevated script additionally bounds and
+ * hashes the exact bytes it decodes.
  */
 export interface StagedWindowsTaskXml {
   /** Path inside the caller's hardened staging directory. */
   readonly path: string;
+  /** Exact byte length, checked before the elevated process allocates or reads. */
+  readonly byteLength: number;
   /** Lowercase hex SHA-256 of the staged bytes (UTF-16LE, no BOM). */
   readonly sha256: string;
 }
@@ -677,16 +683,18 @@ export interface StagedWindowsTaskXml {
 /**
  * Read a staged payload, prove it is the one that was validated, and decode it.
  *
- * One read: the bytes that are hashed are the same array that is decoded and registered.
- * Hashing a path and then reopening it would reintroduce the swap window this check
- * exists to close.
+ * One bounded read: the bytes that are hashed are the same array that is decoded and
+ * registered. The unelevated launcher keeps the namespace and files pinned throughout.
  */
-const READ_STAGED_TASK_XML = "function Read-OcxStagedTaskXml([string]$path, [string]$expectedHash) {"
+const READ_STAGED_TASK_XML = "function Read-OcxStagedTaskXml([string]$path, [long]$expectedLength, [string]$expectedHash) {"
   // An unreadable payload is a diagnosable condition, not a generic throw: a hidden
   // elevated process has nowhere to print, so the cause has to ride the exit code.
-  + " try { $bytes = [IO.File]::ReadAllBytes($path) }"
+  + " try { $stream = [IO.File]::Open($path, 'Open', 'Read', 'Read');"
+  + " if ($stream.Length -ne $expectedLength) { throw 'Task Scheduler staged payload has an invalid length.' };"
+  + " $bytes = [byte[]]::new($expectedLength); $offset = 0;"
+  + " while ($offset -lt $bytes.Length) { $read = $stream.Read($bytes, $offset, $bytes.Length - $offset); if ($read -eq 0) { throw 'Task Scheduler staged payload ended early.' }; $offset += $read } }"
   + " catch [System.UnauthorizedAccessException] { exit " + OCX_ELEVATED_STAGING_UNREADABLE + " }"
-  + " catch [System.Security.SecurityException] { exit " + OCX_ELEVATED_STAGING_UNREADABLE + " };"
+  + " catch [System.Security.SecurityException] { exit " + OCX_ELEVATED_STAGING_UNREADABLE + " } finally { if ($null -ne $stream) { $stream.Dispose() } };"
   + " $sha = [Security.Cryptography.SHA256]::Create();"
   + " try { $actual = [BitConverter]::ToString($sha.ComputeHash($bytes)).Replace('-', '').ToLowerInvariant() } finally { $sha.Dispose() };"
   + " if ($actual -cne $expectedHash) { throw 'Task Scheduler staged payload failed its integrity check.' };"
@@ -706,12 +714,12 @@ const READ_STAGED_TASK_XML = "function Read-OcxStagedTaskXml([string]$path, [str
  * The command now carries two paths and two 64-character digests, so its length no
  * longer depends on the size of the XML at all.
  *
- * The original design goal was "immutable bytes, never a caller-writable pathname".
- * That goal is kept by different means rather than abandoned: the staging directory is
- * private and ACL-hardened, the files are created exclusively so nothing can be waiting
- * at the path, and the digest makes a same-account swap during the UAC prompt fail
- * closed instead of registering something else. An ACL alone could not do that last
- * part, because a process running as the same user has the same SID.
+ * The unelevated launcher opens every ancestor and payload with OPEN_REPARSE_POINT,
+ * validates its type, and holds them until the elevated process exits: ancestors deny
+ * delete sharing (read/write stay shared, so sibling files can still be staged) and
+ * each payload denies write/delete sharing.
+ * Thus the privileged open cannot be redirected during UAC; the length and digest are
+ * defense in depth for the bytes read from the pinned regular file.
  *
  * The replacement precondition is unchanged: the elevated process still re-queries the
  * live registration and compares it to the captured predecessor before passing -Force.
@@ -725,18 +733,40 @@ export function runWindowsElevatedScheduledTaskRegistration(
   if (replace && !expectedExisting) {
     throw new Error("Elevated Task Scheduler replacement requires a captured existing definition.");
   }
+  for (const payload of [xml, expectedExisting].filter((value): value is StagedWindowsTaskXml => value !== undefined)) {
+    if (!Number.isSafeInteger(payload.byteLength) || payload.byteLength < 0 || !/^[0-9a-f]{64}$/.test(payload.sha256)) {
+      throw new Error("Elevated Task Scheduler staging metadata is invalid.");
+    }
+  }
   const powerShellPath = windowsPowerShell();
   const powerShellDirectory = powerShellPath.replace(/[\\/][^\\/]+$/, "");
   const scheduledTasksModule = `${powerShellDirectory}\\Modules\\ScheduledTasks\\ScheduledTasks.psd1`;
+  const parentDirectory = (path: string) => path.replace(/[\\/][^\\/]+$/, "");
+  const stageDirectory = parentDirectory(xml.path);
+  // The pin only covers the staging directory itself: a payload nested deeper
+  // would sit inside a folder nobody locked, so each file must name the staging
+  // directory as its immediate parent rather than merely carrying its prefix.
+  // Traversal segments are rejected on either separator before the parent is
+  // compared, and a bare filename has no parent directory at all.
+  const stagedDirectlyInside = (path: string) =>
+    !path.split(/[\\/]+/).includes("..")
+    && parentDirectory(path) === stageDirectory
+    && parentDirectory(path) !== path;
+  if (
+    !stagedDirectlyInside(xml.path)
+    || (expectedExisting && !stagedDirectlyInside(expectedExisting.path))
+  ) {
+    throw new Error("Elevated Task Scheduler payloads must share one staging directory.");
+  }
   const inner = [
     `$taskName = ${psSingleQuote(taskName)}`,
     READ_STAGED_TASK_XML,
-    `$xml = Read-OcxStagedTaskXml ${psSingleQuote(xml.path)} ${psSingleQuote(xml.sha256)}`,
+    `$xml = Read-OcxStagedTaskXml ${psSingleQuote(xml.path)} ${xml.byteLength} ${psSingleQuote(xml.sha256)}`,
     `$module = Microsoft.PowerShell.Core\\Import-Module -Name ${psSingleQuote(scheduledTasksModule)} -PassThru -Force -ErrorAction Stop`,
     "$registerTask = $module.ExportedCommands['Register-ScheduledTask']",
     "if ($null -eq $registerTask) { throw 'Trusted ScheduledTasks module does not export Register-ScheduledTask.' }",
     ...(replace ? [
-      `$expectedXml = Read-OcxStagedTaskXml ${psSingleQuote(expectedExisting!.path)} ${psSingleQuote(expectedExisting!.sha256)}`,
+      `$expectedXml = Read-OcxStagedTaskXml ${psSingleQuote(expectedExisting!.path)} ${expectedExisting!.byteLength} ${psSingleQuote(expectedExisting!.sha256)}`,
       `$schtasks = ${psSingleQuote(resolveTrustedWindowsSchtasksExe())}`,
       "$currentXml = & $schtasks /query /tn $taskName /xml 2>$null | Out-String",
       "if ($LASTEXITCODE -ne 0) { throw 'Task Scheduler replacement precondition could not be read.' }",
@@ -747,6 +777,13 @@ export function runWindowsElevatedScheduledTaskRegistration(
   ].join("; ");
   const encodedCommand = Buffer.from(inner, "utf16le").toString("base64");
   const script = [
+    "Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class OcxStageLock { [StructLayout(LayoutKind.Sequential)] public struct TagInfo { public uint Attributes; public uint Tag; } [DllImport(\"kernel32.dll\", CharSet=CharSet.Unicode, SetLastError=true)] public static extern Microsoft.Win32.SafeHandles.SafeFileHandle CreateFile(string p, uint a, uint s, IntPtr q, uint c, uint f, IntPtr t); [DllImport(\"kernel32.dll\", SetLastError=true)] public static extern bool GetFileInformationByHandleEx(Microsoft.Win32.SafeHandles.SafeFileHandle h, int c, out TagInfo i, uint n); }';",
+    "$locks = @();",
+    "function Lock-OcxStage([string]$path, [bool]$directory) { $flags = 0x00200000; $share = 1; if ($directory) { $flags = $flags -bor 0x02000000; $share = 3 }; $h = [OcxStageLock]::CreateFile($path, 0x80000000, $share, [IntPtr]::Zero, 3, $flags, [IntPtr]::Zero); if ($h.IsInvalid) { throw 'Task Scheduler staging lock failed.' }; $info = [OcxStageLock+TagInfo]::new(); if (![OcxStageLock]::GetFileInformationByHandleEx($h, 9, [ref]$info, 8) -or (($info.Attributes -band 0x400) -ne 0) -or $directory -ne (($info.Attributes -band 0x10) -ne 0)) { $h.Dispose(); throw 'Task Scheduler staging path is redirected or has the wrong type.' }; $script:locks += $h };",
+    `$dir = [IO.DirectoryInfo]::new(${psSingleQuote(stageDirectory)}); $dirs = @(); while ($null -ne $dir) { $dirs += $dir.FullName; $dir = $dir.Parent }; [array]::Reverse($dirs); $dirs | ForEach-Object { Lock-OcxStage $_ $true };`,
+    `Lock-OcxStage ${psSingleQuote(xml.path)} $false;`,
+    ...(expectedExisting ? [`Lock-OcxStage ${psSingleQuote(expectedExisting.path)} $false;`] : []),
+    "try {",
     `$p = Start-Process -FilePath ${psSingleQuote(powerShellPath)}`,
     ` -ArgumentList ${psSingleQuote(buildWindowsElevatedArgumentList([
       "-NoProfile",
@@ -760,7 +797,7 @@ export function runWindowsElevatedScheduledTaskRegistration(
     `if ($null -eq $p) { exit ${OCX_ELEVATED_UAC_CANCELLED} }`,
     "$null = $p.Handle;",
     `if ($null -eq $p.ExitCode) { exit ${OCX_ELEVATED_PROTOCOL_FAILED} }`,
-    "exit $p.ExitCode",
+    "$code = $p.ExitCode } finally { $locks | ForEach-Object { $_.Dispose() } }; exit $code",
   ].join("");
 
   return startPowerShellCommand(script).completion.then(result => result.exitCode);

package/src/lib/windows-secret-acl.ts

@@ -27,6 +27,13 @@
  *   HardenOptions.timeoutMemoKey — optional destination-path key for the
  *     timeout memo (atomic writers mint unique temps; never a parent directory).
  *   hardenSecretDir  — same contract for directories.
+ *   hardenElevatedStagePath / hardenElevatedStageDir — a second, deliberately
+ *     separate ACL shape for NON-secret payloads an elevated process must read
+ *     (issue #4779). It keeps the owner grant and the broad-SID strip but also
+ *     grants read to SYSTEM and BUILTIN\Administrators. It is a distinct export
+ *     — not an option on the secret functions — so a secret call site cannot
+ *     reach the wider shape by accident, and its success memos live in their
+ *     own caches so one shape never satisfies the other's lookup.
  */
 
 import { existsSync, statSync } from "node:fs";
@@ -47,12 +54,32 @@ import {
 
 const hardenedDirectories = new Map<string, HardenedIdentity>();
 const hardenedPaths = new Map<string, HardenedIdentity>();
+/** Elevated-stage memos are kept apart from the secret ones: the ACL shapes differ. */
+const hardenedStageDirectories = new Map<string, HardenedIdentity>();
+const hardenedStagePaths = new Map<string, HardenedIdentity>();
 /**
  * Paths whose harden TIMED OUT this process: do not re-stall every loadConfig on them.
- * `false` means one explicitly authorized recovery attempt remains; `true` means
- * that attempt was consumed. Ordinary callers never consume it.
+ * `consumed: false` means one explicitly authorized recovery attempt remains;
+ * `consumed: true` means that attempt was consumed at `consumedAt`.
+ *
+ * A consumed memo re-arms once per `TIMEOUT_MEMO_REARM_MS` window, and only for a
+ * caller carrying `retryTimedOutOnce` (issue #3522). The destination-keyed memo for a
+ * STABLE path — the response-spill directory — used to refuse every later harden for
+ * the life of the process: one transient icacls outage consumed the single recovery
+ * and durable publication never succeeded again, while the process reported healthy.
+ * The window keeps anti-restall bounded (at most one real attempt per window) while a
+ * recovered runner can clear the memo and resume publication without a restart.
+ */
+const timedOutPaths = new Map<string, { consumed: boolean; consumedAt: number }>();
+
+/**
+ * Quiet period before a consumed timeout memo admits one caller-owned recovery
+ * attempt. Far above the per-harden deadline cap (60s) so a still-stalled icacls
+ * produces at most one bounded probe per window and every other refusal stays
+ * instant; short enough that a recovered icacls resumes same-process hardening
+ * without waiting for a restart.
  */
-const timedOutPaths = new Map<string, boolean>();
+export const TIMEOUT_MEMO_REARM_MS = 5 * 60_000;
 /** Compatibility slack before the outer belt releases a caller whose killed child has not reaped. */
 const ASYNC_ICACLS_BELT_MARGIN_MS = 250;
 const pendingAsyncIcaclsReaps = new Map<string, Set<Promise<void>>>();
@@ -252,7 +279,8 @@ export interface HardenOptions {
   /**
    * Consume the one recovery attempt for a previously timed-out memo key.
    * Only a caller that owns its own single-flight and bounded retry policy should
-   * set this. It never clears or bypasses an already-consumed timeout memo.
+   * set this. It never clears or bypasses an already-consumed timeout memo before
+   * its re-arm window (`TIMEOUT_MEMO_REARM_MS`) has elapsed.
    */
   retryTimedOutOnce?: boolean;
 }
@@ -499,6 +527,8 @@ export function setNowForTests(fn: (() => number) | null): void {
 export function resetHardenedStateForTests(): void {
   hardenedDirectories.clear();
   hardenedPaths.clear();
+  hardenedStageDirectories.clear();
+  hardenedStagePaths.clear();
   timedOutPaths.clear();
 }
 
@@ -568,6 +598,7 @@ export function reattributeHardenedSecretPath(targetPath: string): boolean {
  */
 export function forgetEphemeralSecretPath(tempPath: string): void {
   hardenedPaths.delete(tempPath);
+  hardenedStagePaths.delete(tempPath);
   timedOutPaths.delete(`required:${tempPath}`);
   timedOutPaths.delete(`optional:${tempPath}`);
 }
@@ -575,6 +606,7 @@ export function forgetEphemeralSecretPath(tempPath: string): void {
 /** Directory counterpart for a proven-absent ephemeral staging root. */
 export function forgetEphemeralSecretDir(tempPath: string): void {
   hardenedDirectories.delete(tempPath);
+  hardenedStageDirectories.delete(tempPath);
   timedOutPaths.delete(`required:${tempPath}`);
   timedOutPaths.delete(`optional:${tempPath}`);
 }
@@ -650,10 +682,33 @@ async function currentWindowsPrincipalAsync(deadline: number): Promise<string> {
  */
 const BROAD_SIDS = ["*S-1-1-0", "*S-1-5-11", "*S-1-5-32-545"] as const;
 
+/**
+ * Well-known SIDs an elevated process may run as (#4779).
+ *
+ * An over-the-shoulder UAC prompt answered with a DIFFERENT administrator's
+ * credentials produces an elevated token whose subject is that admin — not the
+ * account that staged the payload. BUILTIN\Administrators covers that token;
+ * SYSTEM covers an elevation launched from a service context. These SIDs are
+ * deliberately absent from BROAD_SIDS: the staged payload must stay readable
+ * by them after /remove:g runs.
+ */
+const ELEVATED_STAGE_READ_SIDS = ["*S-1-5-18", "*S-1-5-32-544"] as const;
+
 function grantAce(user: string, directory: boolean): string {
   return directory ? `${user}:(OI)(CI)(F)` : `${user}:(F)`;
 }
 
+/**
+ * Read-only ACEs for the elevated-stage shape: read on a file, read+traverse
+ * inherited by children on a directory. Read only — tamper-evidence comes from
+ * the pinned handles and the SHA-256 the elevated script verifies, not from the
+ * DACL, so no elevated principal needs write.
+ */
+function elevatedStageReadAces(directory: boolean): string[] {
+  const rights = directory ? "(OI)(CI)(RX)" : "(R)";
+  return ELEVATED_STAGE_READ_SIDS.map(sid => `${sid}:${rights}`);
+}
+
 function existingAclIsCompliant(
   targetPath: string,
   directory: boolean,
@@ -722,7 +777,7 @@ async function existingAclAlreadyCompliantAsync(
   }
 }
 
-function runIcacls(targetPath: string, directory: boolean, deadline: number): void {
+function runIcacls(targetPath: string, directory: boolean, deadline: number, extraReadAces: readonly string[]): void {
   const principal = currentWindowsPrincipal(deadline);
 
   // The deadline is owned by hardenEntry (total budget incl. retry + verification).
@@ -740,7 +795,7 @@ function runIcacls(targetPath: string, directory: boolean, deadline: number): vo
 
   // Step 1: grant current user full control BEFORE any destructive ACL change.
   // If this fails, inheritance is untouched and the writer keeps inherited access.
-  runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(principal, directory)]);
+  runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(principal, directory), ...extraReadAces]);
 
   // Step 2: disable inheritance and remove inherited ACEs. The explicit owner ACE
   // from step 1 survives this transition, so a later failure still leaves cleanup access.
@@ -768,7 +823,7 @@ function runIcacls(targetPath: string, directory: boolean, deadline: number): vo
 }
 
 /** Async counterpart of runIcacls — same step order and timeout/error classification (#612). */
-async function runIcaclsAsync(targetPath: string, directory: boolean, deadline: number): Promise<void> {
+async function runIcaclsAsync(targetPath: string, directory: boolean, deadline: number, extraReadAces: readonly string[]): Promise<void> {
   const principal = await currentWindowsPrincipalAsync(deadline);
 
   const run = async (step: string, args: string[]): Promise<IcaclsResult> => {
@@ -783,7 +838,7 @@ async function runIcaclsAsync(targetPath: string, directory: boolean, deadline:
     if (!result.success) throw icaclsError(step, result);
   };
 
-  await runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(principal, directory)]);
+  await runOrThrow("/grant:r", [targetPath, "/grant:r", grantAce(principal, directory), ...extraReadAces]);
   await runOrThrow("/inheritance:r", [targetPath, "/inheritance:r"]);
 
   const removal = await run("/remove:g", [targetPath, "/remove:g", ...BROAD_SIDS]);
@@ -869,22 +924,30 @@ function previousTimeoutError(retryConsumed: boolean): TimeoutMemoRefusalError {
   ), { aclFailureOrigin: "timeout_memo_refusal" as const });
 }
 
-/** Consume, but never reset, the single explicit recovery attempt for this key. */
+/**
+ * Consume the single explicit recovery attempt for this key. A consumed key re-arms
+ * only after `TIMEOUT_MEMO_REARM_MS` of quiet, and only for `retryTimedOutOnce` —
+ * flagless callers always get an instant refusal.
+ */
 function timeoutMemoErrorIfBlocked(
   memoKey: string,
   opts: HardenOptions,
 ): NodeJS.ErrnoException | null {
-  const retryConsumed = timedOutPaths.get(memoKey);
-  if (retryConsumed === undefined) return null;
-  if (opts.retryTimedOutOnce && retryConsumed === false) {
-    timedOutPaths.set(memoKey, true);
+  const entry = timedOutPaths.get(memoKey);
+  if (entry === undefined) return null;
+  // A re-armed memo reports the plain previous-timeout refusal to flagless callers
+  // (so a retry-owning caller that saw it comes back carrying the flag) but admits
+  // one fresh attempt only to `retryTimedOutOnce`.
+  const rearmed = entry.consumed && nowFn() - entry.consumedAt >= TIMEOUT_MEMO_REARM_MS;
+  if (opts.retryTimedOutOnce && (!entry.consumed || rearmed)) {
+    timedOutPaths.set(memoKey, { consumed: true, consumedAt: nowFn() });
     return null;
   }
-  return previousTimeoutError(retryConsumed);
+  return previousTimeoutError(entry.consumed && !rearmed);
 }
 
 function recordTimeout(memoKey: string): void {
-  if (!timedOutPaths.has(memoKey)) timedOutPaths.set(memoKey, false);
+  if (!timedOutPaths.has(memoKey)) timedOutPaths.set(memoKey, { consumed: false, consumedAt: 0 });
 }
 
 /**
@@ -944,6 +1007,7 @@ function hardenEntry(
   directory: boolean,
   opts: HardenOptions,
   cache: Map<string, HardenedIdentity>,
+  extraReadAces: readonly string[],
 ): HardenResult {
   // Observed absence retires the memo. Leaving it would let a later file at this
   // path satisfy the cache if the filesystem ever hands back a matching identity.
@@ -951,7 +1015,8 @@ function hardenEntry(
   if (effectivePlatform() !== "win32") return { ok: true };
   if (memoSatisfied(cache, targetPath)) return { ok: true };
   const deadline = nowFn() + resolveHardenDeadlineMs(opts.deadlineMs);
-  if (existingAclAlreadyCompliant(targetPath, directory, deadline)) return { ok: true };
+  // The owner-only compliance probe cannot vouch for a shape that also needs read ACEs.
+  if (extraReadAces.length === 0 && existingAclAlreadyCompliant(targetPath, directory, deadline)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   const timeoutMemoError = timeoutMemoErrorIfBlocked(memoKey, opts);
   if (timeoutMemoError) {
@@ -965,7 +1030,7 @@ function hardenEntry(
     try {
       // Captured BEFORE the sequence: this is the file we are about to harden.
       const before = observe(targetPath);
-      runIcacls(targetPath, directory, deadline);
+      runIcacls(targetPath, directory, deadline, extraReadAces);
       if (!recordHarden(cache, targetPath, before)) {
         if (opts.required) throw new Error(SUBSTITUTED_DIAGNOSTIC);
         return { ok: false, diagnostics: SUBSTITUTED_DIAGNOSTIC };
@@ -999,12 +1064,13 @@ async function hardenEntryAsync(
   directory: boolean,
   opts: HardenOptions,
   cache: Map<string, HardenedIdentity>,
+  extraReadAces: readonly string[],
 ): Promise<HardenResult> {
   if (!existsSync(targetPath)) { cache.delete(targetPath); return { ok: true }; }
   if (effectivePlatform() !== "win32") return { ok: true };
   if (memoSatisfied(cache, targetPath)) return { ok: true };
   const deadline = nowFn() + resolveHardenDeadlineMs(opts.deadlineMs);
-  if (await existingAclAlreadyCompliantAsync(targetPath, directory, deadline)) return { ok: true };
+  if (extraReadAces.length === 0 && await existingAclAlreadyCompliantAsync(targetPath, directory, deadline)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   const timeoutMemoError = timeoutMemoErrorIfBlocked(memoKey, opts);
   if (timeoutMemoError) {
@@ -1017,7 +1083,7 @@ async function hardenEntryAsync(
     if (attempt > 0 && deadline - nowFn() <= 0) break;
     try {
       const before = observe(targetPath);
-      await runIcaclsAsync(targetPath, directory, deadline);
+      await runIcaclsAsync(targetPath, directory, deadline, extraReadAces);
       if (!recordHarden(cache, targetPath, before)) {
         if (opts.required) throw new Error(SUBSTITUTED_DIAGNOSTIC);
         return { ok: false, diagnostics: SUBSTITUTED_DIAGNOSTIC };
@@ -1052,7 +1118,7 @@ async function hardenEntryAsync(
  * @param opts        { required: boolean } — required:true throws on failure.
  */
 export function hardenSecretPath(targetPath: string, opts: HardenOptions): HardenResult {
-  return hardenEntry(targetPath, false, opts, hardenedPaths);
+  return hardenEntry(targetPath, false, opts, hardenedPaths, []);
 }
 
 /**
@@ -1060,7 +1126,7 @@ export function hardenSecretPath(targetPath: string, opts: HardenOptions): Harde
  * Same success/timeout/error policy as hardenSecretPath.
  */
 export function hardenSecretPathAsync(targetPath: string, opts: HardenOptions): Promise<HardenResult> {
-  return hardenEntryAsync(targetPath, false, opts, hardenedPaths);
+  return hardenEntryAsync(targetPath, false, opts, hardenedPaths, []);
 }
 
 /**
@@ -1071,12 +1137,37 @@ export function hardenSecretPathAsync(targetPath: string, opts: HardenOptions):
  * @param opts        { required: boolean } — required:true throws on failure.
  */
 export function hardenSecretDir(targetPath: string, opts: HardenOptions): HardenResult {
-  return hardenEntry(targetPath, true, opts, hardenedDirectories);
+  return hardenEntry(targetPath, true, opts, hardenedDirectories, []);
 }
 
 /**
  * Async directory harden (#612). Same policy as hardenSecretDir.
  */
 export function hardenSecretDirAsync(targetPath: string, opts: HardenOptions): Promise<HardenResult> {
-  return hardenEntryAsync(targetPath, true, opts, hardenedDirectories);
+  return hardenEntryAsync(targetPath, true, opts, hardenedDirectories, []);
+}
+
+/**
+ * Harden a NON-secret staged payload that an elevated process must read (#4779).
+ *
+ * Same isolation discipline as {@link hardenSecretPath} — owner full control
+ * granted before inheritance is stripped, broad SIDs removed — plus a read
+ * grant for SYSTEM and BUILTIN\Administrators. An owner-only shape is correct
+ * for secrets and wrong here: a split-token elevation of the staging account
+ * reads either way, but an over-the-shoulder UAC elevation answered with a
+ * different administrator's credentials runs as that admin and could not open
+ * an owner-only payload.
+ *
+ * This is a separate export, not an option on the secret functions, so a
+ * secret call site cannot reach the wider shape by accident. Use it only for
+ * payloads that carry no credentials; their tamper-evidence must come from a
+ * digest verified by the elevated reader, not from the DACL.
+ */
+export function hardenElevatedStagePath(targetPath: string, opts: HardenOptions): HardenResult {
+  return hardenEntry(targetPath, false, opts, hardenedStagePaths, elevatedStageReadAces(false));
+}
+
+/** Directory counterpart of {@link hardenElevatedStagePath}. */
+export function hardenElevatedStageDir(targetPath: string, opts: HardenOptions): HardenResult {
+  return hardenEntry(targetPath, true, opts, hardenedStageDirectories, elevatedStageReadAces(true));
 }

package/src/link/admission-wait.ts

@@ -0,0 +1,73 @@
+export type AuthenticatedCatalogListener = (apiKeyId: string) => void;
+export type OnAuthenticatedCatalog = (listener: AuthenticatedCatalogListener) => () => void;
+
+export interface AdmissionWaitClock {
+  setTimeout: (callback: () => void, ms: number) => unknown;
+  clearTimeout: (timer: unknown) => void;
+}
+
+export class AdmissionWaitError extends Error {
+  readonly code = "admission_timeout";
+
+  constructor(apiKeyId: string, timeoutMs: number) {
+    super(`link key ${apiKeyId} was not admitted within ${timeoutMs}ms`);
+    this.name = "AdmissionWaitError";
+  }
+}
+
+const realClock: AdmissionWaitClock = {
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: timer => clearTimeout(timer as ReturnType<typeof setTimeout>),
+};
+
+export function awaitFirstAdmission(
+  apiKeyId: string,
+  timeoutMs: number,
+  onAuthenticatedCatalog: OnAuthenticatedCatalog,
+  clock?: AdmissionWaitClock,
+): Promise<void>;
+export function awaitFirstAdmission(
+  onAuthenticatedCatalog: OnAuthenticatedCatalog,
+  apiKeyId: string,
+  timeoutMs: number,
+  clock?: AdmissionWaitClock,
+): Promise<void>;
+export function awaitFirstAdmission(
+  first: string | OnAuthenticatedCatalog,
+  second: number | string,
+  third: OnAuthenticatedCatalog | number,
+  fourth?: AdmissionWaitClock,
+): Promise<void> {
+  const apiKeyId = typeof first === "string" ? first : second as string;
+  const timeoutMs = typeof first === "string" ? second as number : third as number;
+  const subscribe = typeof first === "string" ? third as OnAuthenticatedCatalog : first;
+  const clock = fourth ?? realClock;
+  if (!apiKeyId || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    return Promise.reject(new Error("invalid admission wait arguments"));
+  }
+  return new Promise<void>((resolve, reject) => {
+    let settled = false;
+    let timer: unknown;
+    let unsubscribe: (() => void) | undefined;
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clock.clearTimeout(timer);
+      unsubscribe?.();
+      if (error) reject(error);
+      else resolve();
+    };
+    try {
+      timer = clock.setTimeout(() => finish(new AdmissionWaitError(apiKeyId, timeoutMs)), timeoutMs);
+      unsubscribe = subscribe(observedKeyId => {
+        if (observedKeyId === apiKeyId) finish();
+      });
+      if (settled) {
+        unsubscribe();
+        unsubscribe = undefined;
+      }
+    } catch (error) {
+      finish(error instanceof Error ? error : new Error(String(error)));
+    }
+  });
+}

package/src/link/compensation.ts

@@ -0,0 +1,100 @@
+import { chmodSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteFile, isMissingPathError } from "../config/atomic-write";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+import { linkDir } from "./paths";
+
+export interface CompensationEntry {
+  reason: "compensation_failed";
+  since: string;
+}
+
+export interface CompensationStore {
+  version: 1;
+  entries: Record<string, CompensationEntry>;
+}
+
+export class CompensationStoreError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CompensationStoreError";
+  }
+}
+
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+
+export function compensationPath(configDir?: string): string {
+  return join(linkDir(configDir), "compensation.json");
+}
+
+function cloneEmpty(): CompensationStore {
+  return { version: 1, entries: {} };
+}
+
+function assertOnlyKeys(value: Record<string, unknown>, keys: readonly string[], where: string): void {
+  for (const key of Object.keys(value)) {
+    if (!keys.includes(key)) throw new CompensationStoreError(`${where} has an unknown field ${JSON.stringify(key)}`);
+  }
+}
+
+export function parseCompensation(text: string): CompensationStore {
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { throw new CompensationStoreError("compensation.json is not valid JSON"); }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new CompensationStoreError("compensation.json is not an object");
+  const body = raw as Record<string, unknown>;
+  assertOnlyKeys(body, ["version", "entries"], "compensation.json");
+  if (body.version !== 1 || !body.entries || typeof body.entries !== "object" || Array.isArray(body.entries)) {
+    throw new CompensationStoreError("compensation.json has an invalid shape");
+  }
+  const entries: Record<string, CompensationEntry> = {};
+  for (const [linkId, value] of Object.entries(body.entries)) {
+    if (!LINK_ID.test(linkId) || !value || typeof value !== "object" || Array.isArray(value)) {
+      throw new CompensationStoreError("compensation.json has an invalid entry");
+    }
+    const entry = value as Record<string, unknown>;
+    assertOnlyKeys(entry, ["reason", "since"], `compensation.json.entries.${linkId}`);
+    if (entry.reason !== "compensation_failed" || typeof entry.since !== "string" || Number.isNaN(Date.parse(entry.since))) {
+      throw new CompensationStoreError("compensation.json has an invalid entry");
+    }
+    entries[linkId] = { reason: "compensation_failed", since: entry.since };
+  }
+  return { version: 1, entries };
+}
+
+/** Damaged compensation state is display-only evidence and therefore fails closed to empty. */
+export function readCompensation(path: string = compensationPath()): CompensationStore {
+  let text: string;
+  try { text = readFileSync(path, "utf8"); } catch (error) {
+    if (isMissingPathError(error)) return cloneEmpty();
+    return cloneEmpty();
+  }
+  try { return parseCompensation(text); } catch { return cloneEmpty(); }
+}
+
+export function writeCompensation(path: string, store: CompensationStore): void {
+  const normalized = parseCompensation(JSON.stringify(store));
+  const dir = dirname(path);
+  assertNotRealHomeUnderTest(dirname(dir));
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") hardenSecretDir(dir, { required: true });
+  else chmodSync(dir, 0o700);
+  atomicWriteFile(path, `${JSON.stringify(normalized, null, 2)}\n`);
+  if (process.platform !== "win32") chmodSync(path, 0o600);
+}
+
+export function markCompensationFailed(linkId: string, since: string, path: string = compensationPath()): void {
+  const current = readCompensation(path);
+  writeCompensation(path, {
+    version: 1,
+    entries: { ...current.entries, [linkId]: { reason: "compensation_failed", since } },
+  });
+}
+
+export function clearCompensationFailed(linkId: string, path: string = compensationPath()): void {
+  const current = readCompensation(path);
+  if (!current.entries[linkId]) return;
+  const entries = { ...current.entries };
+  delete entries[linkId];
+  writeCompensation(path, { version: 1, entries });
+}

package/src/link/fingerprint.ts

@@ -0,0 +1,21 @@
+export interface ParsedFingerprint {
+  bits: number;
+  fingerprint: string;
+  alias: string;
+  keyType: string;
+}
+
+/** Parse exactly one `ssh-keygen -l` fingerprint line. */
+export function parseFingerprintLine(stdout: string): ParsedFingerprint {
+  if (!stdout || /[\r\n]/.test(stdout)) throw new Error("fingerprint output must contain exactly one line");
+  const match = /^(\d+)\s+(SHA256:[A-Za-z0-9+/=]+)\s+(\S+)\s+\(([^()\s]+)\)$/.exec(stdout);
+  if (!match) throw new Error("fingerprint output has an invalid format");
+  const bits = Number(match[1]);
+  if (!Number.isSafeInteger(bits) || bits < 1) throw new Error("fingerprint bit count is invalid");
+  return {
+    bits,
+    fingerprint: match[2]!,
+    alias: match[3]!,
+    keyType: match[4]!,
+  };
+}