security: Tier 2 review — pagination SSRF fix + threat model + supply-chain audit (#404)

* security: validate pagination 'next' URL origin + Tier 2 review doc

Addresses a HIGH finding from the 2026-04-18 Tier 2 security review
(STRIDE + OWASP API Top 10 + dependency/supply-chain audit):

InvokeNetboxRequest's -All pagination loop passed the server-returned
'next' URL straight into [System.UriBuilder]::new($nextUrl) and then
used the same Authorization headers to fetch it. A compromised NetBox
server or a successful HTTPS MITM could return:

    {"next": "https://attacker.example.com/steal/?cursor=xxx"}

and the client would hand over the live Bearer token in plaintext.
OWASP API10:2023 — Unsafe Consumption of APIs, applied to a client.

Fix adds scheme + host + port comparison against the original request
URI. Mismatched origin throws a descriptive error instead of silently
following. This matches the default behaviour of modern browsers and
most HTTP client libraries regarding Authorization headers across
cross-origin redirects.

4 new unit tests:
- Different host → throws
- Scheme downgrade https→http → throws
- Port change → throws
- Matching scheme/host/port → follows normally (regression)

Review doc (docs/superpowers/reviews/2026-04-18-tier2-security-review.md)
captures the HIGH finding and 5 lower-severity items documented for
follow-up PRs (PSGallery runner version pinning, module code-signing,
Docker digest pinning, optional throttling, SECURITY.md).

Overall posture is strong: zero runtime dependencies, correct URL /
HTML encoding, no dynamic code execution, hardened file upload path,
and all Tier 1 auth/TLS hardening intact.

* security: use Uri.GetLeftPart(Authority) for origin comparison (Gemini round 1)

Gemini flagged the previous scheme/host/port triple-comparison as
unreliable for a real-world edge case:

  [UriBuilder]::new('https', 'netbox.domain.com', 443, '/api/')  → Port=443
  [UriBuilder]::new('https://netbox.domain.com/api/?cursor=x')    → Port=443 (default substituted)

...which is the same. But:

  [UriBuilder]::new('https', 'host', -1, '/api/')                → Port=-1

...would false-positive against any parsed URL that has a resolved
default port. While PowerNetbox's Connect-NBAPI always yields an
explicit port, the Uri.GetLeftPart(Authority) approach is strictly
more robust because it:

1. Normalises both URIs to canonical 'scheme://host[:port]' form
2. Omits the default port when it matches the scheme's default
3. Reduces the check to a single string equality

Verified empirically against the full truth table:
  - same origin, with/without explicit default port: eq=True
  - different host: eq=False
  - different port (non-default): eq=False (e.g. ':8443')
  - different scheme (https→http): eq=False

Added a 5th regression test covering the specific edge case Gemini
raised: URI constructed with explicit port 443, 'next' URL omits the
port. Both normalise to 'https://netbox.domain.com' — should follow.
82/82 Helpers tests pass.

* docs: sync tier 2 review doc with actual GetLeftPart(Authority) fix

Gemini round 2 caught that the review doc still showed the original
scheme/host/port triple-comparison snippet, while the merged code
uses Uri.GetLeftPart(Authority). Updated the snippet and explanation
to match the actual implementation, and bumped the test-count count
from 4 to 5 (the round-1 reply added an explicit-default-port
edge-case regression test).

Gemini's other round-2 comment is a repeat of the round-1 finding
against the pre-fix code — acknowledged but no action needed; the
fix from 0d65d7a is correct.

* fix: replace em-dashes with ASCII hyphens in Helpers tests

PS 5.1 on Windows parses .ps1 files as Windows-1252 when no UTF-8 BOM
is present, which causes non-ASCII characters (em-dash U+2014, etc.)
to produce confusing "Missing closing '}' in statement block" errors
at parse time.

PR #404 introduced two em-dashes in test names and a comment:
  - Context "Pagination next-URL origin validation (... review — TM-1/IV-1)"
  - Inline comment "# No explicit port — UriBuilder fills ..."

Ubuntu / macOS PS 7 parsed them fine, but Windows PS 5.1 CI failed the
whole file's discovery. Same class of bug as v4.5.8.0 PR #398.

Fixed: replaced both em-dashes with ASCII hyphens. 82/82 Helpers tests
still pass locally.

Author: ctrl-alt-automate

Functions/Helpers/InvokeNetboxRequest.ps1

@@ -110,8 +110,24 @@ function InvokeNetboxRequest {
         do {
             $pageNum++
             $currentUri = if ($nextUrl) {
-                # Use the next URL from API response
-                [System.UriBuilder]::new($nextUrl)
+                # Validate that the server-returned pagination URL matches the
+                # original request's origin (scheme + host + port) before
+                # following it. Without this check, a compromised or malicious
+                # NetBox server could redirect pagination to an attacker-
+                # controlled host and receive the Authorization header (Bearer
+                # token) in plaintext.
+                # Reference: 2026-04-18 Tier 2 security review, finding TM-1/IV-1.
+                # Using Uri.GetLeftPart(Authority) gives a canonical
+                # "scheme://host[:port]" that handles default-port substitution
+                # consistently across how the URI was constructed (explicit
+                # port vs parsed from a string).
+                $nextBuilder     = [System.UriBuilder]::new($nextUrl)
+                $originalOrigin  = $URI.Uri.GetLeftPart([System.UriPartial]::Authority)
+                $nextOrigin      = $nextBuilder.Uri.GetLeftPart([System.UriPartial]::Authority)
+                if ($nextOrigin -ne $originalOrigin) {
+                    throw "Refusing to follow pagination 'next' URL to a different origin. Expected $originalOrigin, got $nextOrigin. This may indicate a compromised server or man-in-the-middle attack."
+                }
+                $nextBuilder
             }
             else {
                 $URI

Tests/Helpers.Tests.ps1

@@ -569,6 +569,118 @@ Describe "Helpers tests" -Tag 'Core', 'Helpers' {
                 $result.results | Should -Not -BeNullOrEmpty
             }
         }
+
+        Context "Pagination next-URL origin validation (Tier 2 security review - TM-1/IV-1)" {
+            It "Should throw when 'next' points to a different host" {
+                InModuleScope -ModuleName 'PowerNetbox' {
+                    Mock -CommandName 'Invoke-RestMethod' -MockWith {
+                        return @{
+                            count = 2
+                            next = 'https://attacker.example.com/api/dcim/devices/?limit=1&offset=1'
+                            previous = $null
+                            results = @(@{id=1; name='device1'})
+                        }
+                    }
+
+                    $URI = BuildNewURI -Segments 'dcim', 'devices' -SkipConnectedCheck
+                    { InvokeNetboxRequest -URI $URI -All -PageSize 1 } |
+                        Should -Throw -ExpectedMessage '*Refusing to follow pagination*different origin*attacker.example.com*'
+                }
+            }
+
+            It "Should throw when 'next' downgrades scheme from https to http" {
+                InModuleScope -ModuleName 'PowerNetbox' {
+                    Mock -CommandName 'Invoke-RestMethod' -MockWith {
+                        return @{
+                            count = 2
+                            next = 'http://netbox.domain.com/api/dcim/devices/?limit=1&offset=1'
+                            previous = $null
+                            results = @(@{id=1; name='device1'})
+                        }
+                    }
+
+                    $URI = BuildNewURI -Segments 'dcim', 'devices' -SkipConnectedCheck
+                    { InvokeNetboxRequest -URI $URI -All -PageSize 1 } |
+                        Should -Throw -ExpectedMessage '*Refusing to follow pagination*'
+                }
+            }
+
+            It "Should throw when 'next' changes the port" {
+                InModuleScope -ModuleName 'PowerNetbox' {
+                    Mock -CommandName 'Invoke-RestMethod' -MockWith {
+                        return @{
+                            count = 2
+                            next = 'https://netbox.domain.com:8443/api/dcim/devices/?limit=1&offset=1'
+                            previous = $null
+                            results = @(@{id=1; name='device1'})
+                        }
+                    }
+
+                    $URI = BuildNewURI -Segments 'dcim', 'devices' -SkipConnectedCheck
+                    { InvokeNetboxRequest -URI $URI -All -PageSize 1 } |
+                        Should -Throw -ExpectedMessage '*Refusing to follow pagination*'
+                }
+            }
+
+            It "Should allow 'next' with matching scheme, host, and port" {
+                InModuleScope -ModuleName 'PowerNetbox' {
+                    $script:sameOriginPages = 0
+                    Mock -CommandName 'Invoke-RestMethod' -MockWith {
+                        $script:sameOriginPages++
+                        if ($script:sameOriginPages -eq 1) {
+                            return @{
+                                count = 2
+                                next = 'https://netbox.domain.com/api/dcim/devices/?limit=1&offset=1'
+                                previous = $null
+                                results = @(@{id=1; name='device1'})
+                            }
+                        }
+                        return @{
+                            count = 2
+                            next = $null
+                            previous = $null
+                            results = @(@{id=2; name='device2'})
+                        }
+                    }
+
+                    $URI = BuildNewURI -Segments 'dcim', 'devices' -SkipConnectedCheck
+                    $results = InvokeNetboxRequest -URI $URI -All -PageSize 1
+                    $results.Count | Should -Be 2
+                }
+            }
+
+            It "Should allow 'next' when original URI has explicit default port but 'next' omits it" {
+                # Edge case (Gemini review round 1): URI constructed with
+                # explicit port 443, server returns 'next' without the port.
+                # Both should normalise to the same origin via GetLeftPart.
+                InModuleScope -ModuleName 'PowerNetbox' {
+                    $script:edgeCasePages = 0
+                    Mock -CommandName 'Invoke-RestMethod' -MockWith {
+                        $script:edgeCasePages++
+                        if ($script:edgeCasePages -eq 1) {
+                            return @{
+                                count = 2
+                                # No explicit port - UriBuilder fills 443 but GetLeftPart omits it
+                                next = 'https://netbox.domain.com/api/dcim/devices/?limit=1&offset=1'
+                                previous = $null
+                                results = @(@{id=1; name='device1'})
+                            }
+                        }
+                        return @{
+                            count = 2
+                            next = $null
+                            previous = $null
+                            results = @(@{id=2; name='device2'})
+                        }
+                    }
+
+                    # Construct URI with explicit port 443 to exercise the edge case
+                    $URI = [System.UriBuilder]::new('https', 'netbox.domain.com', 443, '/api/dcim/devices/')
+                    $results = InvokeNetboxRequest -URI $URI -All -PageSize 1
+                    $results.Count | Should -Be 2
+                }
+            }
+        }
     }
 
     Context "InvokeNetboxRequest Error Handling" {