Private/Test-PostureIntegrity.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.

# Build integrity (docs/licensing.md, Hardening). A signed release ships integrity.json: the SHA-256 of every file in the
# module folder, signed with the same ECDSA key family as licences. At import the module hashes itself and records one
# of three states: release (manifest present, trusted signature, every file matches), development (no manifest: a
# source checkout), modified (manifest present but a file differs, a file was added or removed, or the signature does
# not verify). The state is printed in every report header. It is a label, not a lock: anyone can edit it out, and the
# point is that the deliverable they produce says so until they do.

function Get-PostureIntegrityFileList {
    [CmdletBinding()]
    [OutputType([hashtable])]
    param([Parameter(Mandatory)] [string] $ModuleRoot)
    $ErrorActionPreference = 'Stop'
    $root = (Resolve-Path -LiteralPath $ModuleRoot).Path
    $files = @{}
    foreach ($f in Get-ChildItem -Path $root -Recurse -File) {
        $rel = $f.FullName.Substring($root.Length).TrimStart('/', '\') -replace '\\', '/'
        if ($rel -eq 'integrity.json' -or $rel -like '.*' -or $rel -like '*/.*') { continue }
        $files[$rel] = (Get-FileHash -LiteralPath $f.FullName -Algorithm SHA256).Hash.ToLowerInvariant()
    }
    return $files
}

function ConvertTo-PostureIntegrityCanonical {
    [CmdletBinding()]
    [OutputType([byte[]])]
    param([Parameter(Mandatory)] [System.Collections.IDictionary] $Manifest)
    $ErrorActionPreference = 'Stop'
    $files = $Manifest['files']
    # generatedUtc canonicalises as a UTC round-trip string: ConvertFrom-Json hands it back as a DateTime, not the string that was signed.
    $gen = ConvertTo-PostureUtcDateTime $Manifest['generatedUtc']
    $lines = @('tenantkeep-integrity/1', [string]$Manifest['version'], $(if ($gen) { $gen.ToString('o') } else { [string]$Manifest['generatedUtc'] }), [string]$Manifest['keyId'])
    foreach ($k in @($files.Keys | Sort-Object -Culture ([cultureinfo]::InvariantCulture))) { $lines += "$k $([string]$files[$k])" }
    return [System.Text.Encoding]::UTF8.GetBytes(($lines -join "`n"))
}

function New-PostureIntegrityManifest {
    <#
    .SYNOPSIS
        Writes integrity.json into a staged module folder. Build-time only (build.ps1 -Task Integrity); needs the private
        key as a PEM path or a -Signer scriptblock that takes the canonical bytes and returns the signature bytes (Key Vault).
    #>

    [CmdletBinding(SupportsShouldProcess)]
    [OutputType([string])]
    param(
        [Parameter(Mandatory)] [string] $ModuleRoot,
        [Parameter(Mandatory)] [string] $KeyId,
        [string] $PrivateKeyPath,
        [scriptblock] $Signer
    )
    $ErrorActionPreference = 'Stop'
    if (-not $PrivateKeyPath -and -not $Signer) { throw 'New-PostureIntegrityManifest needs -PrivateKeyPath or -Signer.' }
    $root = (Resolve-Path -LiteralPath $ModuleRoot).Path
    $version = [string](Import-PowerShellDataFile -Path (Join-Path $root 'TenantKeep.Posture.psd1')).ModuleVersion
    $manifest = [ordered]@{ format = 'tenantkeep-integrity/1'; version = $version; generatedUtc = [datetime]::UtcNow.ToString('o'); keyId = $KeyId; files = $null; algorithm = 'ES256'; signature = $null }
    $files = Get-PostureIntegrityFileList -ModuleRoot $root
    $ordered = [ordered]@{}; foreach ($k in @($files.Keys | Sort-Object -Culture ([cultureinfo]::InvariantCulture))) { $ordered[$k] = $files[$k] }
    $manifest.files = $ordered
    $bytes = ConvertTo-PostureIntegrityCanonical -Manifest $manifest
    if ($Signer) { $sig = [byte[]](& $Signer $bytes) }
    else {
        $ecdsa = [System.Security.Cryptography.ECDsa]::Create()
        $ecdsa.ImportFromPem((Get-Content -Raw -LiteralPath $PrivateKeyPath))
        $sig = $ecdsa.SignData($bytes, [System.Security.Cryptography.HashAlgorithmName]::SHA256)
    }
    $manifest.signature = [Convert]::ToBase64String($sig)
    $path = Join-Path $root 'integrity.json'
    if ($PSCmdlet.ShouldProcess($path, 'Write integrity manifest')) { [System.IO.File]::WriteAllText($path, (ConvertTo-Json -InputObject $manifest -Depth 5) + "`n", [System.Text.UTF8Encoding]::new($false)) }
    return $path
}

function Test-PostureIntegrity {
    <#
    .SYNOPSIS
        Compares the module folder with its signed integrity.json. Returns state (release, development, modified),
        detail, version and the changed file list.
    #>

    [CmdletBinding()]
    [OutputType([hashtable])]
    param(
        [Parameter(Mandatory)] [string] $ModuleRoot,
        [System.Collections.IDictionary] $PublicKeys
    )
    $ErrorActionPreference = 'Stop'
    $keys = $(if ($PublicKeys) { $PublicKeys } else { $script:PostureLicenceKeys })
    $root = (Resolve-Path -LiteralPath $ModuleRoot).Path
    $manifestPath = Join-Path $root 'integrity.json'
    $version = $(try { [string](Import-PowerShellDataFile -Path (Join-Path $root 'TenantKeep.Posture.psd1')).ModuleVersion } catch { '' })
    if (-not (Test-Path -LiteralPath $manifestPath -PathType Leaf)) { return @{ state = 'development'; detail = 'Development build: no signed release manifest.'; version = $version; changed = @() } }
    $modified = { param([string] $why, [string[]] $changed = @()) @{ state = 'modified'; detail = "Modified build: $why"; version = $version; changed = @($changed) } }
    try { $m = Get-Content -Raw -LiteralPath $manifestPath | ConvertFrom-Json -AsHashtable -Depth 5 } catch { return & $modified 'integrity.json is not valid JSON.' }
    if (-not $m -or [string]$m['format'] -ne 'tenantkeep-integrity/1' -or -not $m.Contains('files') -or -not $m.Contains('signature')) { return & $modified 'integrity.json is not a release manifest.' }
    $keyId = [string]$m['keyId']
    if (-not $keys.Contains($keyId)) { return & $modified "the release manifest is signed with a key this build does not trust ('$keyId')." }
    try {
        $ecdsa = [System.Security.Cryptography.ECDsa]::Create(); $ecdsa.ImportFromPem([string]$keys[$keyId])
        $ok = $ecdsa.VerifyData((ConvertTo-PostureIntegrityCanonical -Manifest $m), [Convert]::FromBase64String([string]$m['signature']), [System.Security.Cryptography.HashAlgorithmName]::SHA256)
    }
    catch { return & $modified "the release manifest signature could not be checked ($($_.Exception.Message))." }
    if (-not $ok) { return & $modified 'the release manifest signature does not match its contents.' }
    $actual = Get-PostureIntegrityFileList -ModuleRoot $root
    $expected = $m['files']
    $changed = [System.Collections.Generic.List[string]]::new()
    foreach ($k in $expected.Keys) { if (-not $actual.ContainsKey($k)) { $changed.Add("$k (removed)") } elseif ($actual[$k] -ne ([string]$expected[$k]).ToLowerInvariant()) { $changed.Add("$k (changed)") } }
    foreach ($k in $actual.Keys) { if (-not $expected.Contains($k)) { $changed.Add("$k (added)") } }
    if ($changed.Count -gt 0) { return & $modified "$($changed.Count) file(s) differ from the signed release $([string]$m['version']): $(@($changed | Sort-Object | Select-Object -First 5) -join ', ')$(if ($changed.Count -gt 5) { ', ...' })." @($changed) }
    return @{ state = 'release'; detail = "Signed release $([string]$m['version'])."; version = [string]$m['version']; changed = @() }
}