From c5b82be8b7e20aa311b8ae11cf8d546c86371c2b Mon Sep 17 00:00:00 2001
From: Jake Sanders <jsanders@endor.ai>
Date: Tue, 4 Aug 2026 15:36:29 -0700
Subject: [PATCH] package-firewall: port the JSON editing primitives to
 PowerShell
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Start of the Windows port. Mirrors the awk primitives in bash/lib/common.sh
function for function, so review is a diff against something already merged.

  Get-EndorB64Url / Get-EndorB64Decode / Get-EndorVSCodeToken / Get-EndorRedactAk
  Get-JsonDoc / Set-JsonDoc
  Get-LineIndent / Get-LineEntryKey
  Get-JsonTopObjectRange / Get-JsonTopObjectBlock
  Set-JsonObjectKeys / Set-JsonTopObjectBlock
  Add-JsonTopLine / Remove-JsonTopKey / Get-JsonTopString
  Test-JsonValid

Line editing rather than ConvertTo-Json, for the same reason the bash side avoids
reserialization and more so: ConvertTo-Json re-indents every line, needs -Depth
raised on 5.1 (the default of 2 silently truncates), and escapes forward slashes
— turning a two-key change into a whole-file rewrite no reviewer can diff.

Get-JsonDoc / Set-JsonDoc carry the newline flavour and the final-newline state
through an edit, so a CRLF file stays CRLF and a file with no trailing newline
keeps not having one. Both are asserted; either would silently break byte-exact
restore.

Test-JsonValid does a structural trailing-comma check on top of
ConvertFrom-Json, because ConvertFrom-Json *accepts* trailing commas in both 5.1
and 7.x — and a trailing comma is precisely the malformation a bad comma rewrite
produces. Without the extra check the validator would wave through the one error
it exists to catch. (The same check is in the bash validator, where node is not
always resolvable.)

Why mirror instead of share: the two ports write the same marker key and the same
patched lines into the same file, and one fleet may be managed by both scripts.
If they drift, one platform's output stops being readable by the other's state
machine — which surfaces as a mysterious re-patch loop rather than an error. The
suites mirror each other assertion for assertion to keep that from happening
quietly.

Tests: 45 assertions, matching the bash suite, plus CRLF round-tripping (which
the bash side has no equivalent for). run-all.ps1 lets a Windows admin validate
without bash or WSL; both runners now discover suites by glob.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 package-firewall/powershell/lib/common.ps1    | 306 ++++++++++++++++++
 package-firewall/tests/README.md              |  12 +-
 package-firewall/tests/powershell/Harness.ps1 |  50 +++
 .../tests/powershell/json-primitives.ps1      | 177 ++++++++++
 package-firewall/tests/run-all.ps1            |  57 ++++
 5 files changed, 599 insertions(+), 3 deletions(-)
 create mode 100644 package-firewall/tests/powershell/Harness.ps1
 create mode 100644 package-firewall/tests/powershell/json-primitives.ps1
 create mode 100755 package-firewall/tests/run-all.ps1

diff --git a/package-firewall/powershell/lib/common.ps1 b/package-firewall/powershell/lib/common.ps1
index 62eaa17..b456bed 100644
--- a/package-firewall/powershell/lib/common.ps1
+++ b/package-firewall/powershell/lib/common.ps1
@@ -19,6 +19,10 @@
 #   Remove-XmlBlock       <path> ...             — strips Endor XML block from settings.xml
 #   Test-KeyConflict      <path> <pattern> <label> — warns when a key exists outside an Endor block
 #   Test-XmlKeyConflict   <path> <pattern> <label> — same, but for XML-comment-delimited blocks
+#
+# VS Code (product.json) — see the "VS Code" section at the bottom of this file:
+#   Get-EndorB64Url / Get-EndorB64Decode         — base64url encode / decode
+#   *-Json*                                       — depth-1 JSON editors that preserve layout
 
 # ╔══════════════════════════════════════════════════════════════════════╗
 # ║  SENTINEL CONTRACT — DO NOT CHANGE THESE STRINGS                    ║
@@ -36,6 +40,15 @@ $ENDOR_BLOCK_END   = '# ===== END ENDOR PACKAGE FIREWALL ====='
 $ENDOR_XML_BLOCK_START = '<!-- ===== BEGIN ENDOR PACKAGE FIREWALL (managed — do not edit) ===== -->'
 $ENDOR_XML_BLOCK_END   = '<!-- ===== END ENDOR PACKAGE FIREWALL ===== -->'
 
+# ╔══════════════════════════════════════════════════════════════════════╗
+# ║  SENTINEL CONTRACT (continued) — the JSON marker key                 ║
+# ║  product.json cannot carry a '#' comment, so the managed marker is a  ║
+# ║  top-level JSON key. It is also the ONLY record of the original       ║
+# ║  extensionsGallery, so changing this string makes every deployed      ║
+# ║  machine unrestorable. Shared with the bash ENDOR_JSON_MARKER_KEY.    ║
+# ╚══════════════════════════════════════════════════════════════════════╝
+$ENDOR_JSON_MARKER_KEY = '_endorPackageFirewall'
+
 # ── User attribution helpers ──────────────────────────────────────────────────
 # Encode <console-user>@<machine> into the Basic-auth username. The firewall
 # decodes the label, auths with the real API key, and logs it as "User".
@@ -50,6 +63,39 @@ function Get-EndorAttrUsername {
     [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("${inner}:${ApiKeyId}"))
 }
 
+# Get-EndorB64Url <text> — base64url. Used for the VS Code gallery URL, where the
+# credential is a path segment rather than userinfo, so '+' and '/' must be
+# substituted rather than percent-encoded. Padding is stripped; the firewall
+# applies strings.TrimRight(token, "=") anyway.
+function Get-EndorB64Url {
+    param([string]$Text)
+    $b64 = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($Text))
+    $b64.Replace('+', '-').Replace('/', '_').TrimEnd('=')
+}
+
+# Get-EndorB64Decode <b64> — decode to a UTF-8 string.
+function Get-EndorB64Decode {
+    param([string]$B64)
+    [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($B64))
+}
+
+# Get-EndorVSCodeToken <attrUser> <secret>
+# Same attributed username as every other ecosystem; the firewall runs
+# applyUserAttribution after resolving the _ak path token.
+function Get-EndorVSCodeToken {
+    param([string]$AttrUser, [string]$Secret)
+    Get-EndorB64Url "${AttrUser}:${Secret}"
+}
+
+# Get-EndorRedactAk <text> — replace the _ak/<token> path segment.
+# A deliberate deviation from the other ecosystems, which echo full credentialed
+# URLs in -DryRun: this token is a bearer credential in a URL *path*, and MDM
+# consoles retain script output for far more people than can read the target file.
+function Get-EndorRedactAk {
+    param([string]$Text)
+    [System.Text.RegularExpressions.Regex]::Replace($Text, '/_ak/[A-Za-z0-9_-]*', '/_ak/<redacted>')
+}
+
 # Get-EndorUrlEncB64 <b64> — percent-encode base64 chars (+ / =) for URL userinfo.
 function Get-EndorUrlEncB64 {
     param([string]$B64)
@@ -585,3 +631,263 @@ function Test-XmlKeyConflict {
         $script:EndorWarned = $true
     }
 }
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# VS Code
+#
+# VS Code reads its extension gallery endpoints from product.json in the install
+# directory. Unlike every other ecosystem here the target file is owned and
+# rewritten by a third party (VS Code's own updater), and it is JSON, so it can
+# carry neither an Endor sentinel comment nor an %ENDOR_*% reference.
+#
+# Hence: a key-level merge into the depth-1 "extensionsGallery" object, a
+# top-level JSON marker key holding the byte-exact original for restore, and a
+# Scheduled Task to re-apply after updates.
+#
+# The editors below are line-oriented rather than using ConvertTo-Json on
+# purpose. ConvertTo-Json would reformat all 2962 lines, reorder nothing but
+# re-indent everything, needs -Depth raised on 5.1 (default 2 silently truncates),
+# and escapes forward slashes — turning a two-line change into a whole-file
+# rewrite that no reviewer can diff. Shipped product.json is pretty-printed one
+# entry per line, so a depth-1 line range is unambiguous. On anything else these
+# editors decline — they return $null and leave the file untouched rather than
+# guessing — so a caller can fall back to a real JSON parser.
+# ══════════════════════════════════════════════════════════════════════════════
+
+# Get-JsonDoc <path>
+# Reads a JSON file preserving the two things line editing would otherwise lose:
+# the newline flavour and whether a final newline was present. Shipped
+# product.json has NO trailing newline, so without this every patch would dirty
+# the last line and a restore could never be byte-exact.
+function Get-JsonDoc {
+    param([string]$FilePath)
+    $raw = [System.IO.File]::ReadAllText($FilePath)
+    if ($raw.Contains("`r`n")) { $nl = "`r`n" } else { $nl = "`n" }
+    $hadFinal = $raw.EndsWith("`n")
+    $lines = [System.Text.RegularExpressions.Regex]::Split($raw, "`r`n|`n")
+    if ($hadFinal -and $lines.Count -gt 0 -and $lines[$lines.Count - 1] -eq '') {
+        $lines = $lines[0..($lines.Count - 2)]
+    }
+    [PSCustomObject]@{ Lines = @($lines); NewLine = $nl; HadFinalNewline = $hadFinal }
+}
+
+# Set-JsonDoc <doc> <path>
+# Writes in place — FileMode.Create truncates the existing file rather than
+# replacing it, so the ACL and file identity survive. UTF-8 without BOM, for the
+# same reason Write-EndorFile does it.
+function Set-JsonDoc {
+    param([PSObject]$Doc, [string]$FilePath)
+    $text = ($Doc.Lines -join $Doc.NewLine)
+    if ($Doc.HadFinalNewline) { $text += $Doc.NewLine }
+    [System.IO.File]::WriteAllText($FilePath, $text, [System.Text.UTF8Encoding]::new($false))
+}
+
+function Get-LineIndent {
+    param([string]$Line)
+    [System.Text.RegularExpressions.Regex]::Match($Line, '^[ \t]*').Value
+}
+
+function Get-LineEntryKey {
+    param([string]$Line)
+    $m = [System.Text.RegularExpressions.Regex]::Match($Line, '^[ \t]*"([^"]+)"[ \t]*:')
+    if ($m.Success) { $m.Groups[1].Value } else { '' }
+}
+
+# Get-JsonTopObjectRange <lines> <key>
+# Locates a depth-1 object value. Returns $null when the key is absent or the
+# file is not line-oriented — the signal to fall back to the node writer.
+function Get-JsonTopObjectRange {
+    param([string[]]$Lines, [string]$Key)
+    $open = '^[ \t]*"' + [System.Text.RegularExpressions.Regex]::Escape($Key) + '"[ \t]*:[ \t]*\{[ \t]*$'
+    for ($i = 0; $i -lt $Lines.Count; $i++) {
+        if ($Lines[$i] -match $open) {
+            $indent = Get-LineIndent $Lines[$i]
+            for ($j = $i + 1; $j -lt $Lines.Count; $j++) {
+                if ($Lines[$j] -eq ($indent + '}') -or $Lines[$j] -eq ($indent + '},')) {
+                    return [PSCustomObject]@{ Start = $i; End = $j; Indent = $indent }
+                }
+            }
+            return $null
+        }
+    }
+    return $null
+}
+
+# Get-JsonTopObjectBlock <lines> <key> — the raw lines of the object, inclusive.
+function Get-JsonTopObjectBlock {
+    param([string[]]$Lines, [string]$Key)
+    $r = Get-JsonTopObjectRange -Lines $Lines -Key $Key
+    if (-not $r) { return $null }
+    @($Lines[$r.Start..$r.End])
+}
+
+# Set-JsonObjectKeys <lines> <key> <setLines> <deleteKeys>
+# Key-level merge into a depth-1 object:
+#   - each entry in <setLines> ('"key": value') replaces the matching entry in
+#     place, keeping its position, or is appended when the key is absent
+#   - each key in <deleteKeys> has its entry removed, however many lines it spans
+#   - entry-terminating commas are recomputed from scratch, so removing or
+#     appending the last entry cannot leave a trailing comma
+# Every other line passes through untouched. Returns $null if <key> was not found.
+#
+# Entries are segmented by indent: a line whose indent equals the first inner
+# line's indent and which starts with "name": opens a new entry, and anything more
+# deeply indented belongs to the entry above. That is what makes the comma rewrite
+# safe across nested arrays such as accessSKUs.
+function Set-JsonObjectKeys {
+    param([string[]]$Lines, [string]$Key, [string[]]$SetLines, [string[]]$DeleteKeys)
+
+    $r = Get-JsonTopObjectRange -Lines $Lines -Key $Key
+    if (-not $r) { return $null }
+
+    $del = @{}
+    foreach ($k in $DeleteKeys) { if ($k) { $del[$k.Trim()] = $true } }
+
+    $entries    = New-Object System.Collections.ArrayList
+    $entryIndex = @{}
+    $innerIndent = $null
+
+    for ($i = $r.Start + 1; $i -lt $r.End; $i++) {
+        $line = $Lines[$i]
+        if ($null -eq $innerIndent) { $innerIndent = Get-LineIndent $line }
+        $key = ''
+        if ((Get-LineIndent $line) -eq $innerIndent) { $key = Get-LineEntryKey $line }
+        if ($key -ne '') {
+            $e = [PSCustomObject]@{ Key = $key; Lines = (New-Object System.Collections.ArrayList); Dropped = $del.ContainsKey($key) }
+            [void]$entries.Add($e)
+            $entryIndex[$key] = $entries.Count - 1
+        }
+        if ($entries.Count -eq 0) {
+            $e = [PSCustomObject]@{ Key = ''; Lines = (New-Object System.Collections.ArrayList); Dropped = $false }
+            [void]$entries.Add($e)
+        }
+        [void]$entries[$entries.Count - 1].Lines.Add($line)
+    }
+    if ($null -eq $innerIndent) { $innerIndent = $r.Indent + "`t" }
+
+    foreach ($sl in $SetLines) {
+        if (-not $sl) { continue }
+        $clean = $sl.Trim()
+        if ($clean -match ',$') { $clean = $clean.Substring(0, $clean.Length - 1) }
+        $k = Get-LineEntryKey $clean
+        if ($entryIndex.ContainsKey($k)) {
+            $e = $entries[$entryIndex[$k]]
+            $e.Lines.Clear(); [void]$e.Lines.Add($innerIndent + $clean); $e.Dropped = $false
+        } else {
+            $e = [PSCustomObject]@{ Key = $k; Lines = (New-Object System.Collections.ArrayList); Dropped = $false }
+            [void]$e.Lines.Add($innerIndent + $clean)
+            [void]$entries.Add($e)
+            $entryIndex[$k] = $entries.Count - 1
+        }
+    }
+
+    $kept = @($entries | Where-Object { -not $_.Dropped })
+    $out  = New-Object System.Collections.ArrayList
+    for ($i = 0; $i -lt $r.Start; $i++) { [void]$out.Add($Lines[$i]) }
+    [void]$out.Add($Lines[$r.Start])
+    for ($n = 0; $n -lt $kept.Count; $n++) {
+        $eLines = @($kept[$n].Lines)
+        for ($m = 0; $m -lt $eLines.Count; $m++) {
+            $line = $eLines[$m]
+            if ($m -eq $eLines.Count - 1) {
+                $line = [System.Text.RegularExpressions.Regex]::Replace($line, ',[ \t]*$', '')
+                if ($n -lt $kept.Count - 1) { $line = $line + ',' }
+            }
+            [void]$out.Add($line)
+        }
+    }
+    for ($i = $r.End; $i -lt $Lines.Count; $i++) { [void]$out.Add($Lines[$i]) }
+    @($out.ToArray())
+}
+
+# Set-JsonTopObjectBlock <lines> <key> <blockLines>
+# Restore path: puts the captured original back verbatim. The trailing comma is
+# taken from whatever is being replaced, so the enclosing object stays valid.
+function Set-JsonTopObjectBlock {
+    param([string[]]$Lines, [string]$Key, [string[]]$BlockLines)
+    $r = Get-JsonTopObjectRange -Lines $Lines -Key $Key
+    if (-not $r) { return $null }
+    $comma = $Lines[$r.End] -match ',[ \t]*$'
+    $blk = @($BlockLines)
+    $last = $blk[$blk.Count - 1]
+    $last = [System.Text.RegularExpressions.Regex]::Replace($last, ',[ \t]*$', '')
+    if ($comma) { $last = $last + ',' }
+    $blk[$blk.Count - 1] = $last
+
+    $out = New-Object System.Collections.ArrayList
+    for ($i = 0; $i -lt $r.Start; $i++) { [void]$out.Add($Lines[$i]) }
+    foreach ($l in $blk) { [void]$out.Add($l) }
+    for ($i = $r.End + 1; $i -lt $Lines.Count; $i++) { [void]$out.Add($Lines[$i]) }
+    @($out.ToArray())
+}
+
+# Add-JsonTopLine <lines> <line>
+# Inserts immediately after the opening brace on line 1, so we emit our own
+# trailing comma and never have to append one to an existing line.
+function Add-JsonTopLine {
+    param([string[]]$Lines, [string]$Line)
+    $out = New-Object System.Collections.ArrayList
+    [void]$out.Add($Lines[0])
+    [void]$out.Add($Line)
+    for ($i = 1; $i -lt $Lines.Count; $i++) { [void]$out.Add($Lines[$i]) }
+    @($out.ToArray())
+}
+
+# Remove-JsonTopKey <lines> <key> — removes a depth-1 single-line key.
+function Remove-JsonTopKey {
+    param([string[]]$Lines, [string]$Key)
+    $pat = '^[ \t]*"' + [System.Text.RegularExpressions.Regex]::Escape($Key) + '"[ \t]*:'
+    @($Lines | Where-Object { $_ -notmatch $pat })
+}
+
+# Get-JsonTopString <lines> <key>
+# Depth-1 string value, anchored to the indent of the first top-level key.
+# product.json contains nested "version" keys hundreds of lines before the
+# top-level one, so an indent-agnostic match returns the wrong value.
+function Get-JsonTopString {
+    param([string[]]$Lines, [string]$Key)
+    if ($Lines.Count -lt 2) { return '' }
+    $tind = Get-LineIndent $Lines[1]
+    $pat = '^' + $tind + '"' + [System.Text.RegularExpressions.Regex]::Escape($Key) + '"[ \t]*:[ \t]*"([^"]*)"'
+    foreach ($l in $Lines) {
+        if ((Get-LineIndent $l) -ne $tind) { continue }
+        $m = [System.Text.RegularExpressions.Regex]::Match($l, $pat)
+        if ($m.Success) { return $m.Groups[1].Value }
+    }
+    return ''
+}
+
+# Test-JsonValid <path>
+# ConvertFrom-Json is native and free, so it always runs — but it is NOT strict:
+# both the 5.1 (Newtonsoft) and 7.x (System.Text.Json) implementations happily
+# accept a trailing comma before } or ]. That is exactly the malformation the
+# comma rewrite in Set-JsonObjectKeys could introduce, so it has to be checked
+# explicitly, or a corrupt product.json would pass validation on Windows while
+# failing in VS Code's own strict JSON.parse.
+#
+# The check is structural rather than a regex over the whole text: a line whose
+# last character is a comma, followed by a line starting with } or ]. A string
+# value can never end in a bare comma (it ends in a quote), so this cannot
+# false-positive on content — which matters, because a false positive here means
+# refusing to apply an otherwise-good patch.
+function Test-JsonValid {
+    param([string]$FilePath)
+    if (-not (Test-Path -LiteralPath $FilePath)) { return $false }
+    try {
+        $raw = [System.IO.File]::ReadAllText($FilePath)
+        if (-not $raw.TrimStart().StartsWith('{')) { return $false }
+        if (-not $raw.TrimEnd().EndsWith('}')) { return $false }
+        $null = $raw | ConvertFrom-Json
+
+        $lines = [System.Text.RegularExpressions.Regex]::Split($raw, "`r`n|`n")
+        $prev = ''
+        foreach ($l in $lines) {
+            $t = $l.Trim()
+            if ($t -eq '') { continue }
+            if ($prev.EndsWith(',') -and ($t.StartsWith('}') -or $t.StartsWith(']'))) { return $false }
+            $prev = $t
+        }
+        return $true
+    } catch { return $false }
+}
diff --git a/package-firewall/tests/README.md b/package-firewall/tests/README.md
index 110b75a..12bb116 100644
--- a/package-firewall/tests/README.md
+++ b/package-firewall/tests/README.md
@@ -4,14 +4,18 @@ Tests for the VS Code ecosystem.
 
 ```sh
 cd package-firewall/tests
-./run-all.sh                 # every suite
+./run-all.sh                 # every suite (adds the PowerShell suites when pwsh is present)
 ./run-all.sh --bash          # bash suites only
 ./run-all.sh json            # suites matching a name
+./run-all.ps1                # PowerShell suites, from Windows without bash or WSL
 ```
 
 Suites are discovered by glob (`bash/*.sh`, `powershell/*.ps1`, minus the harness), so
 adding one needs no edit to the runner. Individual suites run standalone too:
-`bash bash/json-primitives.sh`.
+`bash bash/json-primitives.sh`, `pwsh -NoProfile -File powershell/json-primitives.ps1`.
+
+The two `json-primitives` suites mirror each other assertion for assertion. That
+duplication is deliberate — see reason 3 below.
 
 ## Why VS Code has tests when the other ecosystems don't
 
@@ -37,13 +41,15 @@ byte-level fidelity wrong:
 
 | Path | |
 |---|---|
-| `run-all.sh` | runner; aggregates tallies, non-zero on any failure |
+| `run-all.sh`, `run-all.ps1` | runners; aggregate tallies, non-zero on any failure |
 | `fixtures/product.json` | synthetic `product.json` — the target for almost everything |
 | `bash/harness.sh` | paths, assertion helpers, the stripped-lib loader, fixture installs |
 | `bash/json-primitives.sh` | the awk JSON editing primitives in isolation |
 | `bash/lib.sh` | `vscode_*` lifecycle: discovery, state machine, both writers, failure modes |
 | `bash/watcher.sh` | launchd plist, systemd units, cron fallback, sidecar telemetry |
 | `bash/e2e.sh` | the generated scripts, against a sandboxed install |
+| `powershell/Harness.ps1` | the PowerShell harness |
+| `powershell/json-primitives.ps1` | mirror of `bash/json-primitives.sh`, plus CRLF fidelity |
 
 ## The fixture, and why not a real install
 
diff --git a/package-firewall/tests/powershell/Harness.ps1 b/package-firewall/tests/powershell/Harness.ps1
new file mode 100644
index 0000000..cd677be
--- /dev/null
+++ b/package-firewall/tests/powershell/Harness.ps1
@@ -0,0 +1,50 @@
+# Shared harness for the PowerShell suites. Dot-sourced, never run directly.
+
+# ─── Paths ────────────────────────────────────────────────────────────────────
+# Derived from this file's location, so the suites run from any cwd and from a
+# checkout at any path.
+$script:TESTS_DIR = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$script:PF_DIR    = (Resolve-Path (Join-Path $TESTS_DIR '..')).Path
+$script:PS_DIR    = Join-Path $PF_DIR 'powershell'
+$script:LIB       = Join-Path $PS_DIR 'lib/common.ps1'
+$script:FIXTURE   = Join-Path $TESTS_DIR 'fixtures/product.json'
+
+# Facts about the fixture that several suites assert against. The bash harness
+# carries the same set; they must agree, because both ports are tested against the
+# same file and the sentinel contract requires their output to be interchangeable.
+$script:FIXTURE_LINES         = 74   # real lines; the last one has no newline
+$script:FIXTURE_GALLERY_LINES = 28   # extensionsGallery incl. opening and closing
+$script:FIXTURE_GALLERY_KEYS  = 9
+$script:FIXTURE_SKUS          = 16
+$script:FIXTURE_VERSION       = '1.999.0'
+$script:FIXTURE_COMMIT        = '0123456789abcdef0123456789abcdef01234567'
+
+# ─── Counters ─────────────────────────────────────────────────────────────────
+$script:pass = 0; $script:fail = 0; $script:skipped = 0
+function ok($m)   { Write-Host "  ok   $m"; $script:pass++ }
+function bad($m)  { Write-Host "  FAIL $m"; $script:fail++ }
+function skip($m) { Write-Host "  skip $m"; $script:skipped++ }
+function chk($m, $got, $want) {
+    if ("$got" -eq "$want") { ok $m } else { bad "$m (got [$got] want [$want])" }
+}
+
+# Summarize — print the tally and exit. Last line of every suite.
+function Summarize {
+    Write-Host ''
+    if ($script:skipped -gt 0) {
+        Write-Host "passed $script:pass, failed $script:fail, skipped $script:skipped"
+    } else {
+        Write-Host "passed $script:pass, failed $script:fail"
+    }
+    if ($script:fail -gt 0) { exit 1 }
+}
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+# Get-DiffLineCount — the equivalent of `diff a b | grep -c '^[<>]'`, without
+# needing git or diff on the box. Used to assert that a patch touches only the
+# lines it claims to.
+function Get-DiffLineCount([string]$A, [string]$B) {
+    $x = [System.IO.File]::ReadAllText($A) -split "`r`n|`n"
+    $y = [System.IO.File]::ReadAllText($B) -split "`r`n|`n"
+    (Compare-Object -ReferenceObject $x -DifferenceObject $y).Count
+}
diff --git a/package-firewall/tests/powershell/json-primitives.ps1 b/package-firewall/tests/powershell/json-primitives.ps1
new file mode 100644
index 0000000..f8dad76
--- /dev/null
+++ b/package-firewall/tests/powershell/json-primitives.ps1
@@ -0,0 +1,177 @@
+#!/usr/bin/env pwsh
+# The PowerShell JSON primitives, mirroring tests/bash/json-primitives.sh
+# assertion for assertion.
+#
+# The mirroring is the point. The two generators write the same marker key and the
+# same patched lines into the same file, and an admin may well run the bash script on
+# a Mac and the PowerShell one on Windows against installs managed as one fleet. If
+# the ports drift — a different indent, a different comma, a different marker shape —
+# one platform's output stops being readable by the other's state machine, and that
+# shows up as a mysterious re-patch loop rather than as an error.
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'Harness.ps1')
+. $LIB
+
+$T = Join-Path ([System.IO.Path]::GetTempPath()) ("psjson-" + [guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Path $T | Out-Null
+try {
+
+$PJ       = Join-Path $T 'product.json'
+$PRISTINE = Join-Path $T 'pristine.json'
+Copy-Item $FIXTURE $PJ
+Copy-Item $FIXTURE $PRISTINE
+
+$URL = 'https://factory.endorlabs.com/v1/namespaces/spiderman/firewall/vscode/_ak/dGVzdDp0b2tlbg'
+$SET = @("`"serviceUrl`": `"$URL`"")
+$DEL = @('extensionUrlTemplate')
+
+Write-Host '== 1. document round-trip preserves layout =='
+$doc = Get-JsonDoc $PJ
+chk 'final newline absent, as in a shipped product.json' $doc.HadFinalNewline 'False'
+chk 'newline flavour detected as LF' ($doc.NewLine -eq "`n") 'True'
+chk 'line count' $doc.Lines.Count $FIXTURE_LINES
+Set-JsonDoc -Doc $doc -FilePath $PJ
+chk 'read plus write with no edits is byte-identical' `
+  ((Get-FileHash $PJ).Hash -eq (Get-FileHash $PRISTINE).Hash) 'True'
+
+Write-Host '== 2. extract a depth-1 object =='
+$blk = Get-JsonTopObjectBlock -Lines $doc.Lines -Key 'extensionsGallery'
+chk 'block line count' $blk.Count $FIXTURE_GALLERY_LINES
+chk 'opening line' ($blk[0] -replace "`t", '@') '@"extensionsGallery": {'
+chk 'closing line' ($blk[$blk.Count - 1] -replace "`t", '@') '@},'
+chk 'a missing key returns null' ($null -eq (Get-JsonTopObjectBlock -Lines $doc.Lines -Key 'noSuchKey')) 'True'
+chk 'top-level version, not the nested one in builtInExtensions' `
+  (Get-JsonTopString -Lines $doc.Lines -Key 'version') $FIXTURE_VERSION
+chk 'top-level commit' (Get-JsonTopString -Lines $doc.Lines -Key 'commit') $FIXTURE_COMMIT
+
+Write-Host '== 3. the actual patch: set serviceUrl, delete extensionUrlTemplate =='
+$doc = Get-JsonDoc $PJ
+$new = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines $SET -DeleteKeys $DEL
+if ($null -eq $new) { bad 'merge returned null' } else {
+    $doc.Lines = $new; Set-JsonDoc -Doc $doc -FilePath $PJ
+    if (Test-JsonValid $PJ) { ok 'valid JSON' } else { bad 'INVALID JSON' }
+    $g = (Get-Content $PJ -Raw | ConvertFrom-Json).extensionsGallery
+    chk 'serviceUrl set' ($g.serviceUrl -eq $URL) 'True'
+    chk 'extensionUrlTemplate gone (the 5xx unpkg bypass)' ($null -eq $g.extensionUrlTemplate) 'True'
+    chk "controlUrl left alone (Microsoft's revocation list)" ($g.controlUrl.StartsWith('https://main.vscode-cdn.net')) 'True'
+    chk 'resourceUrlTemplate left alone' ($g.resourceUrlTemplate.StartsWith('https://{publisher}')) 'True'
+    chk 'accessSKUs untouched by a key-level merge' $g.accessSKUs.Count $FIXTURE_SKUS
+    chk 'final-newline fidelity kept' ((Get-JsonDoc $PJ).HadFinalNewline) 'False'
+    # One line replaced plus one line removed. This is what makes "one key set, one
+    # key removed" a checked claim rather than an intention.
+    chk 'diff touches only the 2 intended keys' (Get-DiffLineCount $PRISTINE $PJ) 3
+}
+
+Write-Host '== 4. delete the LAST entry, which is multi-line =='
+# JSON has no trailing commas, so removing the final entry must fix up the one before.
+$doc = Get-JsonDoc $PRISTINE
+$doc.Lines = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines @() -DeleteKeys @('accessSKUs')
+$P2 = Join-Path $T 'droplast.json'; Set-JsonDoc -Doc $doc -FilePath $P2
+if (Test-JsonValid $P2) { ok 'valid JSON after dropping the last multi-line entry' } else { bad 'INVALID' }
+$blk2 = Get-JsonTopObjectBlock -Lines (Get-JsonDoc $P2).Lines -Key 'extensionsGallery'
+chk 'the entry before it lost its comma' ($blk2[$blk2.Count - 2].Trim()) `
+  '"mcpUrl": "https://main.vscode-cdn.net/mcp/servers.json"'
+
+Write-Host '== 5. delete the FIRST entry, and append a new key =='
+$doc = Get-JsonDoc $PRISTINE
+$doc.Lines = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines @() -DeleteKeys @('nlsBaseUrl')
+$P3 = Join-Path $T 'dropfirst.json'; Set-JsonDoc -Doc $doc -FilePath $P3
+if (Test-JsonValid $P3) { ok 'valid after dropping the first entry' } else { bad 'INVALID' }
+$g3 = (Get-Content $P3 -Raw | ConvertFrom-Json).extensionsGallery
+chk 'first entry gone, the rest intact' `
+  (($null -eq $g3.nlsBaseUrl) -and ($g3.PSObject.Properties.Name.Count -eq ($FIXTURE_GALLERY_KEYS - 1))) 'True'
+
+$doc = Get-JsonDoc $PRISTINE
+$doc.Lines = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines @('"endorProbe": "x"') -DeleteKeys @()
+$P4 = Join-Path $T 'append.json'; Set-JsonDoc -Doc $doc -FilePath $P4
+if (Test-JsonValid $P4) { ok 'valid after appending a new key' } else { bad 'INVALID' }
+chk 'appended value readable' ((Get-Content $P4 -Raw | ConvertFrom-Json).extensionsGallery.endorProbe) 'x'
+chk 'the preceding entry gained its comma' `
+  ((Get-Content $P4 -Raw | ConvertFrom-Json).extensionsGallery.accessSKUs.Count) $FIXTURE_SKUS
+
+Write-Host '== 6. idempotency =='
+$h1 = (Get-FileHash $PJ).Hash
+$doc = Get-JsonDoc $PJ
+$doc.Lines = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines $SET -DeleteKeys $DEL
+Set-JsonDoc -Doc $doc -FilePath $PJ
+chk 're-merge is byte-identical' ((Get-FileHash $PJ).Hash -eq $h1) 'True'
+
+Write-Host '== 7. restore round-trip =='
+$doc = Get-JsonDoc $PJ
+$doc.Lines = Set-JsonTopObjectBlock -Lines $doc.Lines -Key 'extensionsGallery' -BlockLines $blk
+Set-JsonDoc -Doc $doc -FilePath $PJ
+chk 'restored byte-identical to pristine' ((Get-FileHash $PJ).Hash -eq (Get-FileHash $PRISTINE).Hash) 'True'
+
+Write-Host '== 8. marker insert and removal =='
+$MARK = "`t`"_endorPackageFirewall`": {`"schema`":1,`"namespace`":`"spiderman`"},"
+$doc = Get-JsonDoc $PJ
+$doc.Lines = Add-JsonTopLine -Lines $doc.Lines -Line $MARK
+$P5 = Join-Path $T 'marked.json'; Set-JsonDoc -Doc $doc -FilePath $P5
+if (Test-JsonValid $P5) { ok 'valid JSON with the marker' } else { bad 'INVALID with the marker' }
+chk 'marker readable by a real parser' ((Get-Content $P5 -Raw | ConvertFrom-Json)._endorPackageFirewall.namespace) 'spiderman'
+$doc = Get-JsonDoc $P5
+$doc.Lines = Remove-JsonTopKey -Lines $doc.Lines -Key '_endorPackageFirewall'
+$P6 = Join-Path $T 'unmarked.json'; Set-JsonDoc -Doc $doc -FilePath $P6
+chk 'marker removal is byte-exact' ((Get-FileHash $P6).Hash -eq (Get-FileHash $PRISTINE).Hash) 'True'
+
+Write-Host '== 9. shapes other than the shipped one =='
+# 4-space indentation: the indent must be read from the file, never assumed.
+$SP = Join-Path $T 'sp.json'
+[System.IO.File]::WriteAllText($SP, "{`n    `"a`": 1,`n    `"extensionsGallery`": {`n        `"serviceUrl`": `"old`",`n        `"extensionUrlTemplate`": `"u`",`n        `"itemUrl`": `"i`"`n    },`n    `"z`": 2`n}`n")
+$doc = Get-JsonDoc $SP
+$doc.Lines = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines $SET -DeleteKeys $DEL
+Set-JsonDoc -Doc $doc -FilePath $SP
+if (Test-JsonValid $SP) { ok '4-space-indented file valid' } else { bad 'space-indented INVALID' }
+$o = Get-Content $SP -Raw | ConvertFrom-Json
+chk 'space-indented: edit applied' ($o.extensionsGallery.serviceUrl -eq $URL) 'True'
+chk 'space-indented: siblings intact' ($o.extensionsGallery.itemUrl + '/' + $o.z) 'i/2'
+chk "the set line took the file's own 8-space indent, not a tab" `
+  ((Get-LineIndent (Get-Content $SP | Where-Object { $_ -match 'factory' } | Select-Object -First 1)).Length) 8
+chk 'space-indented file kept its final newline' ((Get-JsonDoc $SP).HadFinalNewline) 'True'
+
+# Deleting the sole entry must leave a valid empty object, not a dangling comma.
+$ONLY = Join-Path $T 'only.json'
+[System.IO.File]::WriteAllText($ONLY, "{`n`t`"extensionsGallery`": {`n`t`t`"extensionUrlTemplate`": `"u`"`n`t}`n}`n")
+$doc = Get-JsonDoc $ONLY
+$doc.Lines = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines @() -DeleteKeys $DEL
+Set-JsonDoc -Doc $doc -FilePath $ONLY
+if (Test-JsonValid $ONLY) { ok 'deleting the sole entry leaves a valid empty object' }
+else { bad "sole-entry delete INVALID: $(Get-Content $ONLY -Raw)" }
+
+# Minified: no depth-1 line range to edit, so the line writer must decline. That
+# refusal is what hands off to the node writer.
+$MIN = Join-Path $T 'min.json'
+[System.IO.File]::WriteAllText($MIN, '{"extensionsGallery":{"serviceUrl":"old"},"z":1}')
+chk 'minified: range lookup returns null (the fallback trigger)' `
+  ($null -eq (Get-JsonTopObjectRange -Lines (Get-JsonDoc $MIN).Lines -Key 'extensionsGallery')) 'True'
+chk 'minified: merge returns null' `
+  ($null -eq (Set-JsonObjectKeys -Lines (Get-JsonDoc $MIN).Lines -Key 'extensionsGallery' -SetLines $SET -DeleteKeys $DEL)) 'True'
+
+Write-Host '== 10. a CRLF file stays CRLF =='
+# Windows tooling and some repackagers produce CRLF. Rewriting even one line to LF
+# would show up as a whole-file diff and break byte-exact restore.
+$CRLF = Join-Path $T 'crlf.json'
+[System.IO.File]::WriteAllText($CRLF, "{`r`n`t`"extensionsGallery`": {`r`n`t`t`"serviceUrl`": `"old`"`r`n`t}`r`n}")
+$doc = Get-JsonDoc $CRLF
+chk 'CRLF detected' ($doc.NewLine -eq "`r`n") 'True'
+$doc.Lines = Set-JsonObjectKeys -Lines $doc.Lines -Key 'extensionsGallery' -SetLines $SET -DeleteKeys $DEL
+Set-JsonDoc -Doc $doc -FilePath $CRLF
+if (Test-JsonValid $CRLF) { ok 'CRLF file still valid' } else { bad 'CRLF INVALID' }
+chk 'CRLF preserved on write' ([System.IO.File]::ReadAllText($CRLF).Contains("`r`n")) 'True'
+chk 'no bare LF introduced' `
+  ([regex]::Matches([System.IO.File]::ReadAllText($CRLF), "(?<!`r)`n").Count) 0
+
+Write-Host '== 11. validation refuses what it must =='
+$BAD = Join-Path $T 'bad.json'; [System.IO.File]::WriteAllText($BAD, 'not json at all')
+chk 'rejects non-JSON' (Test-JsonValid $BAD) 'False'
+# ConvertFrom-Json accepts trailing commas in both 5.1 and 7.x, so validity alone is
+# not enough — and a trailing comma is exactly what a bad comma rewrite produces.
+$TC = Join-Path $T 'tc.json'; [System.IO.File]::WriteAllText($TC, "{`n`t`"a`": 1,`n}")
+chk 'rejects a trailing comma, which ConvertFrom-Json would accept' (Test-JsonValid $TC) 'False'
+$GOOD = Join-Path $T 'good.json'; [System.IO.File]::WriteAllText($GOOD, "{`n`t`"a`": 1`n}")
+chk 'accepts good JSON' (Test-JsonValid $GOOD) 'True'
+
+} finally {
+    Remove-Item -Recurse -Force $T -ErrorAction SilentlyContinue
+}
+Summarize
diff --git a/package-firewall/tests/run-all.ps1 b/package-firewall/tests/run-all.ps1
new file mode 100755
index 0000000..3cf04a7
--- /dev/null
+++ b/package-firewall/tests/run-all.ps1
@@ -0,0 +1,57 @@
+#!/usr/bin/env pwsh
+# Runs the PowerShell suites and aggregates the tallies.
+#
+#   ./run-all.ps1              all PowerShell suites
+#   ./run-all.ps1 lib          only suites whose name matches
+#
+# This exists so a Windows admin can validate before pushing to a fleet without
+# needing bash or WSL. The bash suites cover the same ground for macOS and Linux and
+# are run by ./run-all.sh — which will also run these when pwsh is on PATH.
+#
+# Suites are discovered by glob (powershell/*.ps1, minus the dot-sourced harness), so
+# adding one needs no edit here.
+#
+# Nothing here needs Administrator, and nothing touches an installed VS Code: the
+# suites work on copies of tests/fixtures/product.json inside a temp directory.
+param([string[]]$Filter = @())
+
+Set-Location $PSScriptRoot
+
+$suites = Get-ChildItem -LiteralPath 'powershell' -Filter '*.ps1' |
+    Where-Object { $_.Name -ne 'Harness.ps1' } |
+    Sort-Object Name
+
+$totPass = 0; $totFail = 0; $totSkip = 0; $failedSuites = @(); $ran = 0
+
+foreach ($s in $suites) {
+    $name = 'powershell/' + $s.BaseName
+    if ($Filter.Count -gt 0 -and -not ($Filter | Where-Object { $name -like "*$_*" })) { continue }
+    Write-Host ''
+    Write-Host "--- $name ---"
+    $out = & pwsh -NoProfile -File $s.FullName 2>&1 | Out-String
+    $rc = $LASTEXITCODE
+    Write-Host $out.TrimEnd()
+    $ran++
+
+    $m = [regex]::Match($out, 'passed (\d+), failed (\d+)(?:, skipped (\d+))?')
+    if ($m.Success) {
+        $totPass += [int]$m.Groups[1].Value
+        $totFail += [int]$m.Groups[2].Value
+        if ($m.Groups[3].Success) { $totSkip += [int]$m.Groups[3].Value }
+    } else {
+        # No tally means the suite died before finishing, which must not read as a pass.
+        $totFail += 1
+    }
+    if ($rc -ne 0) { $failedSuites += $name }
+}
+
+Write-Host ''
+Write-Host '--- total ---'
+if ($ran -eq 0) { Write-Host 'no suites matched'; exit 1 }
+if ($totSkip -gt 0) { Write-Host "passed $totPass, failed $totFail, skipped $totSkip" }
+else { Write-Host "passed $totPass, failed $totFail" }
+if ($failedSuites.Count -gt 0) {
+    Write-Host "failing suites: $($failedSuites -join ', ')"
+    exit 1
+}
+if ($totFail -gt 0) { exit 1 }