Require terminal ownership proof and typed publication metadata

Reuse the provenance footer for stable PR releases, preserve raw API object and collection shapes, and share typed immutable tag reads. Escape module-name dots without altering Gallery names or payload metadata.

Author: MariusStorhaug

.github/actions/Publish-PSModule/README.md

@@ -2,14 +2,16 @@
 
 Publishes a pre-versioned, tested PowerShell module artifact to the PowerShell Gallery after source-bound ownership preflight. GitHub Release creation is handled by the separate [Release-PSModule](../Release-PSModule/README.md) action.
 
-The publisher verifies the original source, exact resolved tag/version, producing repository/PR or direct-release context, and tested bytes before an external versioned-artifact mutation. An absent Gallery module/version is reserved at `PSModule-Publication/<lowercase-module>/<lowercase-version>`, independently of the configured release-tag prefix. The shared coordinate and release tag reference the same immutable annotated source/context/file-tree/ZIP claim. Existing tags are never updated or deleted; the package ownership coordinate is retained for immutable Gallery proof.
+The publisher verifies the original source, exact resolved tag/version, producing repository/PR or direct-release context, and tested bytes before an external versioned-artifact mutation. An absent Gallery module/version is reserved at `PSModule-Publication/<escaped-lowercase-module>/<lowercase-version>`, independently of the configured release-tag prefix. Module-name dots are encoded as `%2e` so valid dotted names cannot produce Git-invalid `..` or `.lock` components. The shared coordinate and release tag reference the same immutable annotated source/context/file-tree/ZIP claim. Existing tags are never updated or deleted; the package ownership coordinate is retained for immutable Gallery proof.
 
 An observed release tag must remain unchanged through shared coordinate creation. If it disappears or is replaced during that reservation, the attempt fails instead of recreating it. A valid partial shared claim can still create an absent release tag that has never been observed in the attempt.
 
 An existing Gallery package is retained only when its raw nupkg payload matches that proof and the tested artifact. Package code is never imported to establish ownership. Unknown legacy proof, foreign tags/releases/assets, changed claims, authentication errors, and API failures stop publication explicitly.
 
 Provenance must contain one original JSON object with scalar proof fields; arrays are not projected into valid identities. The ZIP's exact bytes and canonical payload digest are verified together against the tested file tree before a claim or Gallery write. Original event PR context is validated before normalized fields are selected.
 
+GitHub resource responses must have valid object/scalar shapes, while verified empty tag collections remain valid absence. An existing PR-produced stable or prerelease release requires its producing-context footer; unreadable terminal markers are errors even when indented or inline. Unknown legacy PR release context is not inferred from a matching tag.
+
 ## Inputs
 
 | Name | Description | Required | Default |

.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1

@@ -128,7 +128,7 @@ function Invoke-PSModulePublicationApi {
         throw "The GitHub API response for [$Endpoint] has no verifiable JSON body."
     }
     $body = $parts[1] -replace '(?m)^gh:.*(?:\r?\n|\z)', ''
-    $value = $body | ConvertFrom-Json -ErrorAction Stop
+    $value = ConvertFrom-Json -InputObject $body -NoEnumerate -ErrorAction Stop
     if ($null -eq $value) {
         throw "The GitHub API response for [$Endpoint] returned no resource metadata."
     }
@@ -302,60 +302,67 @@ function Get-PSModulePublicationReader {
 
     Write-Verbose "Binding publication readers to [$Repository]."
     $requiresWriteAccess = -not $ReadOnly
+    $readTagReference = {
+        param($Tag)
+        $encodedTag = [Uri]::EscapeDataString($Tag)
+        $response = Invoke-PSModulePublicationApi -Endpoint "repos/$Repository/git/ref/tags/$encodedTag" -AllowMissing
+        if ($null -eq $response) { return }
+        $value = $response.Value
+        if ($value -isnot [PSCustomObject] -or $value -is [array] -or
+            $value.ref -isnot [string] -or $value.ref -cne "refs/tags/$Tag" -or
+            $value.object -isnot [PSCustomObject] -or $value.object -is [array] -or
+            $value.object.sha -isnot [string] -or $value.object.sha -notmatch '^[0-9a-f]{40}$' -or
+            $value.object.type -isnot [string] -or $value.object.type -cnotin @('tag', 'commit')) {
+            throw "The tag lookup for [$Tag] returned unverifiable reference metadata."
+        }
+        $value.object
+    }.GetNewClosure()
     @{
         GetSource                = {
             param($CommitSha)
             $repositoryMetadata = (Invoke-PSModulePublicationApi -Endpoint "repos/$Repository").Value
-            if ($repositoryMetadata.full_name -ine $Repository) {
+            if ($repositoryMetadata -isnot [PSCustomObject] -or $repositoryMetadata -is [array] -or
+                $repositoryMetadata.full_name -isnot [string] -or $repositoryMetadata.full_name -ine $Repository) {
                 throw "Cannot establish access to the exact consumer repository [$Repository]."
             }
-            if ($requiresWriteAccess -and $repositoryMetadata.permissions.push -ne $true) {
+            if ($requiresWriteAccess -and ($repositoryMetadata.permissions.push -isnot [bool] -or
+                    $repositoryMetadata.permissions.push -ne $true)) {
                 throw "Cannot verify release visibility and write access in [$Repository]. Refusing to treat hidden releases as absent."
             }
             $commit = (Invoke-PSModulePublicationApi -Endpoint "repos/$Repository/git/commits/$CommitSha").Value
-            if ($commit.sha -cne $CommitSha) {
+            if ($commit -isnot [PSCustomObject] -or $commit -is [array] -or
+                $commit.sha -isnot [string] -or $commit.sha -cne $CommitSha) {
                 throw "Cannot verify the original immutable source [$CommitSha] in [$Repository]."
             }
             [string]$commit.sha
         }.GetNewClosure()
-        GetTagReference          = {
-            param($Tag)
-            $encodedTag = [Uri]::EscapeDataString($Tag)
-            $response = Invoke-PSModulePublicationApi -Endpoint "repos/$Repository/git/ref/tags/$encodedTag" -AllowMissing
-            if ($null -eq $response) {
-                return
-            }
-            if ($response.Value.ref -cne "refs/tags/$Tag" -or $null -eq $response.Value.object) {
-                throw "The tag lookup for [$Tag] did not return the exact tag reference."
-            }
-            $response.Value.object
-        }.GetNewClosure()
+        GetTagReference          = $readTagReference
         GetVersionReference      = {
             param($Name, $Version)
             $tag = Get-PSModulePublicationVersionTag -ModuleName $Name -GalleryVersion $Version
-            $encodedTag = [Uri]::EscapeDataString($tag)
-            $response = Invoke-PSModulePublicationApi -Endpoint "repos/$Repository/git/ref/tags/$encodedTag" -AllowMissing
-            if ($null -eq $response) {
-                return
-            }
-            if ($response.Value.ref -cne "refs/tags/$tag" -or $null -eq $response.Value.object) {
-                throw "Cannot verify the shared module/version ownership coordinate [$tag]."
-            }
-            $response.Value.object
+            & $readTagReference $tag
         }.GetNewClosure()
         GetTagObject             = {
             param($Sha)
             $response = (Invoke-PSModulePublicationApi -Endpoint "repos/$Repository/git/tags/$Sha").Value
-            if ($response.sha -cne $Sha -or $null -eq $response.object -or
-                $response.PSObject.Properties.Name -notcontains 'message') {
+            if ($response -isnot [PSCustomObject] -or $response -is [array] -or
+                $response.sha -isnot [string] -or $response.sha -cne $Sha -or $response.tag -isnot [string] -or
+                $response.object -isnot [PSCustomObject] -or $response.object -is [array] -or
+                $response.object.type -isnot [string] -or $response.object.sha -isnot [string] -or
+                $response.object.sha -notmatch '^[0-9a-f]{40}$' -or $response.message -isnot [string]) {
                 throw "Cannot verify the annotated publication tag [$Sha]."
             }
             $response
         }.GetNewClosure()
         GetRelease               = {
             param($Tag)
             $encodedTag = [Uri]::EscapeDataString($Tag)
-            (Invoke-PSModulePublicationApi -Endpoint "repos/$Repository/releases/tags/$encodedTag" -AllowMissing).Value
+            $response = Invoke-PSModulePublicationApi -Endpoint "repos/$Repository/releases/tags/$encodedTag" -AllowMissing
+            if ($null -eq $response) { return }
+            if ($response.Value -isnot [PSCustomObject] -or $response.Value -is [array]) {
+                throw "The release lookup for [$Tag] returned unverifiable resource metadata."
+            }
+            $response.Value
         }.GetNewClosure()
         GetPackage               = {
             param($Name, $Version)
@@ -510,7 +517,7 @@ function Get-PSModulePublicationState {
             throw "Cannot verify the existing release context for [$($expected.ReleaseTag)]."
         }
         $owner = Get-PSModulePrereleaseOwnership -Body $release.body
-        if ($null -ne $owner -or ($expected.ReleaseType -ceq 'Prerelease' -and $expected.PullRequest -gt 0)) {
+        if ($null -ne $owner -or $expected.PullRequest -gt 0) {
             if ($expected.PullRequest -lt 1) {
                 throw 'The existing release ownership footer conflicts with the direct-release context.'
             }
@@ -522,6 +529,9 @@ function Get-PSModulePublicationState {
             throw 'The existing release contains foreign or ambiguous module assets.'
         }
         if ($assets.Count -eq 1) {
+            if ($assets[0].name -isnot [string] -or $assets[0].digest -isnot [string] -or $assets[0].state -isnot [string]) {
+                throw 'The existing module asset has unverifiable byte-proof metadata.'
+            }
             $digest = [regex]::Match([string]$assets[0].digest, '^sha256:([0-9A-Fa-f]{64})$')
             if (-not $digest.Success -or $assets[0].state -cne 'uploaded') {
                 throw "The existing asset [$($expected.AssetName)] has no verifiable published-byte proof."
@@ -615,7 +625,10 @@ function New-PSModulePublicationTag {
         }
         $tag = (Invoke-PSModulePublicationApi -Endpoint "repos/$($Claim.Repository)/git/tags" `
                 -Method POST -Field $tagFields).Value
-        if ($tag.sha -notmatch '^[0-9a-f]{40}$' -or $tag.tag -cne $Claim.ReleaseTag -or
+        if ($tag -isnot [PSCustomObject] -or $tag -is [array] -or
+            $tag.sha -isnot [string] -or $tag.sha -notmatch '^[0-9a-f]{40}$' -or $tag.tag -isnot [string] -or
+            $tag.message -isnot [string] -or $tag.object.sha -isnot [string] -or $tag.object.type -isnot [string] -or
+            $tag.tag -cne $Claim.ReleaseTag -or
             $tag.object.type -cne 'commit' -or $tag.object.sha -cne $Claim.CommitSha -or $tag.message -cne $message) {
             throw 'The annotated object did not preserve the exact source/context/artifact claim.'
         }

.github/actions/Publish-PSModule/tests/Publish-PSModule.Preflight.Tests.ps1

@@ -183,11 +183,15 @@ Describe 'Publish-PSModule source-bound preflight' {
         @{ Resource = 'repository array' }
         @{ Resource = 'commit array' }
         @{ Resource = 'string write permission' }
+        @{ Resource = 'release ref array' }
+        @{ Resource = 'annotation target array' }
+        @{ Resource = 'release array' }
+        @{ Resource = 'asset digest array' }
     ) {
         if ($Resource -ceq 'commit array') {
             $endpoint = "repos/PSModule/TestModule/git/commits/$env:GITHUB_SHA"
             $script:state.ApiResponses[$endpoint] = @([pscustomobject]@{ sha = $env:GITHUB_SHA })
-        } else {
+        } elseif ($Resource -in @('repository array', 'string write permission')) {
             $metadata = [pscustomobject]@{
                 full_name = 'PSModule/TestModule'; permissions = [pscustomobject]@{ push = $true }
             }
@@ -197,14 +201,37 @@ Describe 'Publish-PSModule source-bound preflight' {
             } else {
                 $script:state.ApiResponses['repos/PSModule/TestModule'] = @($metadata)
             }
+        } else {
+            Set-PSModuleFixtureClaim -State $script:state -Claim $script:state.ExpectedClaim
+            if ($Resource -ceq 'release ref array') {
+                $script:state.ApiResponses['repos/PSModule/TestModule/git/ref/tags/v1.2.4'] = @([pscustomobject]@{
+                        ref = 'refs/tags/v1.2.4'; object = $script:state.Tag
+                    })
+            } elseif ($Resource -ceq 'annotation target array') {
+                $script:state.TagObject.object = @([pscustomobject]@{ type = 'commit'; sha = $env:GITHUB_SHA })
+            } else {
+                $release = [pscustomobject]@{
+                    tag_name = 'v1.2.4'; html_url = 'https://github.com/PSModule/TestModule/releases/tag/v1.2.4'
+                    prerelease = $false; draft = $false; body = 'Direct release notes.'; assets = @()
+                }
+                if ($Resource -ceq 'release array') {
+                    $script:state.ApiResponses['repos/PSModule/TestModule/releases/tags/v1.2.4'] = @($release)
+                } else {
+                    $release.assets = @([pscustomobject]@{
+                            name = 'TestModule-1.2.4.zip'; state = 'uploaded'
+                            digest = @("sha256:$($script:state.ExpectedClaim.AssetSha256)")
+                        })
+                    $script:state.Release = $release
+                }
+            }
         }
 
         $failure = $null
         try { & $script:publishScriptPath 1>$null 6>$null } catch { $failure = $_ }
 
         $script:state.GalleryWrites | Should -Be 0
         $script:state.GitHubWrites | Should -Be 0
-        $failure.Exception.Message | Should -Match 'metadata|access|source'
+        $failure.Exception.Message | Should -Match 'metadata|access|source|tag'
     }
 
     It 'retains a verified empty tag enumeration instead of treating it as an unknown JSON response' {
@@ -582,6 +609,65 @@ Describe 'Publish-PSModule source-bound preflight' {
         $script:state.Release.body | Should -BeExactly $originalNotes
     }
 
+    It 'rejects array-valued release <Field> metadata before any claim or upload' -ForEach @(
+        @{ Field = 'Title' }
+        @{ Field = 'Body' }
+        @{ Field = 'HeadRef' }
+    ) {
+        $context = @{ Number = 42 }
+        $context[$Field] = @('Unverifiable projected metadata.')
+        $env:PSMODULE_RELEASE_PSMODULE_INPUT_PullRequest = $context | ConvertTo-Json -Compress
+
+        { & $script:releaseScriptPath 1>$null 6>$null } | Should -Throw '*metadata*'
+
+        $script:state.GalleryWrites | Should -Be 0
+        $script:state.GitHubWrites | Should -Be 0
+    }
+
+    It 'rejects <Shape> generated stable notes before release creation or upload' -ForEach @(
+        @{ Shape = 'array-valued body' }
+        @{ Shape = 'top-level array' }
+    ) {
+        $script:state.ExpectedClaim.PullRequest = 42
+        $env:PSMODULE_RELEASE_PSMODULE_INPUT_PullRequest = '{"Number":42}'
+        [IO.File]::WriteAllText($env:GITHUB_EVENT_PATH, '{"head_commit":{"message":""}}')
+        Mock -CommandName git -MockWith {
+            $global:LASTEXITCODE = 0
+            ''
+        }
+        $notes = [pscustomobject]@{ body = 'Complete notes.' }
+        if ($Shape -ceq 'array-valued body') {
+            $notes.body = @('Incomplete projected notes.')
+            $script:state.ApiResponses['repos/PSModule/TestModule/releases/generate-notes'] = $notes
+        } else {
+            $script:state.ApiResponses['repos/PSModule/TestModule/releases/generate-notes'] = @($notes)
+        }
+
+        { & $script:releaseScriptPath 1>$null 6>$null } | Should -Throw '*notes*'
+
+        Should -Invoke -CommandName git -Times 1 -Exactly
+        ($script:state.Calls -join "`n") | Should -Match 'releases/generate-notes'
+        $script:state.GalleryWrites | Should -Be 0
+        $script:state.GitHubCreationUpload | Should -Be 0
+    }
+
+    It 'retains complete generated stable notes before the producing-context footer' {
+        $script:state.ExpectedClaim.PullRequest = 42
+        $env:PSMODULE_RELEASE_PSMODULE_INPUT_PullRequest = '{"Number":42}'
+        [IO.File]::WriteAllText($env:GITHUB_EVENT_PATH, '{"head_commit":{"message":""}}')
+        Mock -CommandName git -MockWith {
+            $global:LASTEXITCODE = 0
+            ''
+        }
+
+        { & $script:releaseScriptPath 1>$null 6>$null } | Should -Not -Throw
+
+        Should -Invoke -CommandName git -Times 1 -Exactly
+        ($script:state.Calls -join "`n") | Should -Match 'releases/generate-notes'
+        $script:state.Release.body | Should -Match '^Complete independently generated fixture notes\.'
+        (Get-PSModulePrereleaseOwnership -Body $script:state.Release.body).PullRequest | Should -Be 42
+    }
+
     It 'rejects a disappeared previously claimed tag rather than recreating it' {
         Set-PSModuleFixtureClaim -State $script:state -Claim $script:state.ExpectedClaim
         $script:state.OnTagRead = {

.github/actions/Release-PSModule/README.md

@@ -50,4 +50,4 @@ Release creation and upload recheck the release tag, shared module/version coord
 
 The local ZIP's exact bytes and payload digest are verified together against the tested file tree before claiming, creating, or uploading. Original event PR context and versioned provenance must have valid object/scalar shapes before normalization; arrays cannot supply publication ownership.
 
-Complete authored or generated prerelease notes precede a final repository/producing-PR/source footer. A matching tag/source does not authorize another PR's release. Legacy records without proof require reviewed forward-only recovery; the action does not fabricate provenance or alter consumer metadata.
+Complete authored or generated notes for PR-produced stable and prerelease releases precede the same final repository/producing-PR/source footer. A matching tag/source does not authorize another PR's release, and an existing PR release without that proof is not resumed. Indented, inline, or unreadable terminal ownership markers fail explicitly. Direct stable releases retain their genuinely absent PR context. Legacy records without proof require reviewed forward-only recovery; the action does not fabricate provenance or alter consumer metadata.