@rover-studio/answer-me 0.1.0-rc.1

package/distribution/npm/skills/answerme/scripts/creator-credential-store.windows.ps1

@@ -0,0 +1,503 @@
+$ErrorActionPreference = 'Stop'
+
+$cryptoSupport = Join-Path $PSScriptRoot 'windows-crypto.ps1'
+if (-not (Test-Path -LiteralPath $cryptoSupport -PathType Leaf)) {
+    throw 'The AnswerMe Windows cryptography helper is missing.'
+}
+. $cryptoSupport
+
+function New-AnswerMeCreatorCredentialStoreException {
+    param(
+        [Parameter(Mandatory = $true)][string]$Code,
+        [Parameter(Mandatory = $true)][string]$Stage,
+        [Parameter(Mandatory = $true)][string]$Message,
+        [bool]$TargetChanged = $false,
+        [bool]$BackupCreated = $false,
+        [string]$RollbackStatus = 'not-required'
+    )
+
+    $exception = [InvalidOperationException]::new($Message)
+    $exception.Data['AnswerMeCode'] = $Code
+    $exception.Data['AnswerMeStage'] = $Stage
+    $exception.Data['AnswerMeTargetChanged'] = $TargetChanged
+    $exception.Data['AnswerMeBackupCreated'] = $BackupCreated
+    $exception.Data['AnswerMeRollbackStatus'] = $RollbackStatus
+    $exception.Data['AnswerMeNetworkCalled'] = $false
+    return $exception
+}
+
+function Test-AnswerMeCreatorCredentialLoopbackHost {
+    param([Parameter(Mandatory = $true)][Uri]$Uri)
+
+    return $Uri.DnsSafeHost.Equals('localhost', [StringComparison]::OrdinalIgnoreCase) -or
+        $Uri.DnsSafeHost.Equals('127.0.0.1', [StringComparison]::Ordinal) -or
+        $Uri.DnsSafeHost.Equals('::1', [StringComparison]::Ordinal)
+}
+
+function Resolve-AnswerMeCreatorCredentialApiBaseUrl {
+    param(
+        [AllowNull()][string]$ApiBaseUrl,
+        [switch]$AllowInsecureLoopbackHttpForTest
+    )
+
+    if ([string]::IsNullOrWhiteSpace($ApiBaseUrl)) {
+        throw 'A trusted API base URL is required.'
+    }
+
+    $parsed = $null
+    if (-not [Uri]::TryCreate($ApiBaseUrl, [UriKind]::Absolute, [ref]$parsed)) {
+        throw 'The API base URL is invalid.'
+    }
+    if (-not [string]::IsNullOrEmpty($parsed.UserInfo) -or
+        -not [string]::IsNullOrEmpty($parsed.Query) -or
+        -not [string]::IsNullOrEmpty($parsed.Fragment) -or
+        $parsed.AbsolutePath -notin @('', '/')) {
+        throw 'The API base URL must not include credentials, a path, a query, or a fragment.'
+    }
+    if ($parsed.Scheme -ne 'https' -and -not (
+        $parsed.Scheme -eq 'http' -and
+        $AllowInsecureLoopbackHttpForTest -and
+        (Test-AnswerMeCreatorCredentialLoopbackHost -Uri $parsed)
+    )) {
+        throw 'The API base URL must use HTTPS.'
+    }
+
+    return $parsed.AbsoluteUri.TrimEnd('/')
+}
+
+function Get-AnswerMeDefaultCreatorCredentialPath {
+    if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
+        throw 'The Windows Creator Credential Store requires Windows.'
+    }
+    $localAppData = [Environment]::GetFolderPath([Environment+SpecialFolder]::LocalApplicationData)
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        throw 'The current Windows account has no LocalApplicationData directory.'
+    }
+    return [IO.Path]::GetFullPath((Join-Path $localAppData 'AnswerMe\creator-credential.clixml'))
+}
+
+function Get-AnswerMeCreatorCredentialSecureBytes {
+    param([Parameter(Mandatory = $true)][Security.SecureString]$SecureValue)
+
+    $bstr = [IntPtr]::Zero
+    try {
+        $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($SecureValue)
+        $byteLength = [Runtime.InteropServices.Marshal]::ReadInt32($bstr, -4)
+        $bytes = [byte[]]::new($byteLength)
+        if ($byteLength -gt 0) {
+            [Runtime.InteropServices.Marshal]::Copy($bstr, $bytes, 0, $byteLength)
+        }
+        return ,$bytes
+    }
+    finally {
+        if ($bstr -ne [IntPtr]::Zero) {
+            [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
+        }
+    }
+}
+
+function Test-AnswerMeCreatorCredentialSecureEqual {
+    param(
+        [Parameter(Mandatory = $true)][Security.SecureString]$Left,
+        [Parameter(Mandatory = $true)][Security.SecureString]$Right
+    )
+
+    [byte[]]$leftBytes = Get-AnswerMeCreatorCredentialSecureBytes -SecureValue $Left
+    [byte[]]$rightBytes = Get-AnswerMeCreatorCredentialSecureBytes -SecureValue $Right
+    $leftHash = $null
+    $rightHash = $null
+    try {
+        $leftHash = Get-AnswerMeSha256Bytes -Bytes $leftBytes
+        $rightHash = Get-AnswerMeSha256Bytes -Bytes $rightBytes
+        return Test-AnswerMeFixedTimeBytesEqual -Left $leftHash -Right $rightHash
+    }
+    finally {
+        if ($null -ne $leftBytes) {
+            Clear-AnswerMeSensitiveByteArray -Bytes $leftBytes
+        }
+        if ($null -ne $rightBytes) {
+            Clear-AnswerMeSensitiveByteArray -Bytes $rightBytes
+        }
+        if ($null -ne $leftHash) {
+            Clear-AnswerMeSensitiveByteArray -Bytes $leftHash
+        }
+        if ($null -ne $rightHash) {
+            Clear-AnswerMeSensitiveByteArray -Bytes $rightHash
+        }
+    }
+}
+
+function Get-AnswerMeCreatorCredentialFileHash {
+    param([Parameter(Mandatory = $true)][string]$LiteralPath)
+
+    $bytes = [IO.File]::ReadAllBytes($LiteralPath)
+    try {
+        return ,(Get-AnswerMeSha256Bytes -Bytes $bytes)
+    }
+    finally {
+        Clear-AnswerMeSensitiveByteArray -Bytes $bytes
+    }
+}
+
+function Test-AnswerMeCreatorCredentialBytesEqual {
+    param(
+        [Parameter(Mandatory = $true)][byte[]]$Left,
+        [Parameter(Mandatory = $true)][byte[]]$Right
+    )
+
+    return Test-AnswerMeFixedTimeBytesEqual -Left $Left -Right $Right
+}
+
+function Import-AnswerMeCreatorCredentialFile {
+    param([Parameter(Mandatory = $true)][string]$LiteralPath)
+
+    return Import-Clixml -LiteralPath $LiteralPath
+}
+
+function Export-AnswerMeCreatorCredentialFile {
+    param(
+        [Parameter(Mandatory = $true)][PSCredential]$Credential,
+        [Parameter(Mandatory = $true)][string]$LiteralPath
+    )
+
+    $Credential | Export-Clixml -LiteralPath $LiteralPath
+}
+
+function Invoke-AnswerMeCreatorCredentialAtomicReplace {
+    param(
+        [Parameter(Mandatory = $true)][string]$SourcePath,
+        [Parameter(Mandatory = $true)][string]$TargetPath,
+        [AllowNull()][string]$BackupPath,
+        [bool]$TargetExists
+    )
+
+    if ($TargetExists) {
+        [IO.File]::Replace($SourcePath, $TargetPath, $BackupPath, $true)
+    }
+    else {
+        [IO.File]::Move($SourcePath, $TargetPath)
+    }
+}
+
+function Restore-AnswerMeCreatorCredentialTarget {
+    param(
+        [Parameter(Mandatory = $true)][string]$TargetPath,
+        [AllowNull()][string]$BackupPath,
+        [AllowNull()][byte[]]$OriginalFileHash,
+        [bool]$TargetPreviouslyExisted,
+        [Parameter(Mandatory = $true)][string]$RollbackTemporaryPath
+    )
+
+    if ($TargetPreviouslyExisted) {
+        if (Test-Path -LiteralPath $TargetPath -PathType Leaf) {
+            [byte[]]$currentHash = Get-AnswerMeCreatorCredentialFileHash -LiteralPath $TargetPath
+            try {
+                if (Test-AnswerMeCreatorCredentialBytesEqual -Left $OriginalFileHash -Right $currentHash) {
+                    return $true
+                }
+            }
+            finally {
+                Clear-AnswerMeSensitiveByteArray -Bytes $currentHash
+            }
+        }
+        if ([string]::IsNullOrWhiteSpace($BackupPath) -or
+            -not (Test-Path -LiteralPath $BackupPath -PathType Leaf)) {
+            return $false
+        }
+        [IO.File]::Copy($BackupPath, $RollbackTemporaryPath, $false)
+        $displacedPath = $RollbackTemporaryPath + '.displaced'
+        try {
+            if (Test-Path -LiteralPath $TargetPath -PathType Leaf) {
+                Invoke-AnswerMeCreatorCredentialAtomicReplace `
+                    -SourcePath $RollbackTemporaryPath `
+                    -TargetPath $TargetPath `
+                    -BackupPath $displacedPath `
+                    -TargetExists $true
+            }
+            else {
+                Invoke-AnswerMeCreatorCredentialAtomicReplace `
+                    -SourcePath $RollbackTemporaryPath `
+                    -TargetPath $TargetPath `
+                    -BackupPath $null `
+                    -TargetExists $false
+            }
+        }
+        finally {
+            if (Test-Path -LiteralPath $displacedPath -PathType Leaf) {
+                Remove-Item -LiteralPath $displacedPath -Force -ErrorAction SilentlyContinue
+            }
+        }
+        if (-not (Test-Path -LiteralPath $TargetPath -PathType Leaf)) {
+            return $false
+        }
+        [byte[]]$restoredHash = Get-AnswerMeCreatorCredentialFileHash -LiteralPath $TargetPath
+        try {
+            return Test-AnswerMeCreatorCredentialBytesEqual -Left $OriginalFileHash -Right $restoredHash
+        }
+        finally {
+            Clear-AnswerMeSensitiveByteArray -Bytes $restoredHash
+        }
+    }
+
+    if (Test-Path -LiteralPath $TargetPath -PathType Leaf) {
+        [IO.File]::Delete($TargetPath)
+    }
+    return -not (Test-Path -LiteralPath $TargetPath)
+}
+
+function Install-AnswerMeCreatorCredential {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)][Security.SecureString]$CreatorKey,
+        [Parameter(Mandatory = $true)][string]$ApiBaseUrl,
+        [Parameter(Mandatory = $true)][string]$CreatorId,
+        [string]$TargetCredentialPath,
+        [switch]$AllowInsecureLoopbackHttpForTest
+    )
+
+    $normalizedApiBaseUrl = $null
+    $resolvedTargetPath = $null
+    $targetParent = $null
+    $targetPreviouslyExisted = $false
+    $originalCredential = $null
+    $originalFileHash = $null
+    try {
+        if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
+            throw 'The Windows Creator Credential Store requires Windows.'
+        }
+        if ([string]::IsNullOrWhiteSpace($CreatorId)) {
+            throw 'Creator ID is required.'
+        }
+        if ($CreatorKey.Length -eq 0) {
+            throw 'Creator Key is empty.'
+        }
+        $normalizedApiBaseUrl = Resolve-AnswerMeCreatorCredentialApiBaseUrl `
+            -ApiBaseUrl $ApiBaseUrl `
+            -AllowInsecureLoopbackHttpForTest:$AllowInsecureLoopbackHttpForTest
+        if ([string]::IsNullOrWhiteSpace($TargetCredentialPath)) {
+            $TargetCredentialPath = Get-AnswerMeDefaultCreatorCredentialPath
+        }
+        $resolvedTargetPath = [IO.Path]::GetFullPath($TargetCredentialPath)
+        if ([IO.Path]::GetExtension($resolvedTargetPath) -cne '.clixml') {
+            throw 'The Creator credential target must be a .clixml file.'
+        }
+        if (Test-Path -LiteralPath $resolvedTargetPath -PathType Container) {
+            throw 'The Creator credential target is not a file.'
+        }
+        $targetParent = [IO.Path]::GetDirectoryName($resolvedTargetPath)
+        if ([string]::IsNullOrWhiteSpace($targetParent)) {
+            throw 'The Creator credential target has no parent directory.'
+        }
+
+        $targetPreviouslyExisted = Test-Path -LiteralPath $resolvedTargetPath -PathType Leaf
+        if ($targetPreviouslyExisted) {
+            $originalCredential = Import-AnswerMeCreatorCredentialFile -LiteralPath $resolvedTargetPath
+            if ($originalCredential -isnot [PSCredential] -or
+                [string]::IsNullOrWhiteSpace($originalCredential.UserName) -or
+                $originalCredential.Password.Length -eq 0) {
+                throw 'The existing Creator credential target has an unknown format.'
+            }
+            try {
+                $null = Resolve-AnswerMeCreatorCredentialApiBaseUrl `
+                    -ApiBaseUrl $originalCredential.UserName `
+                    -AllowInsecureLoopbackHttpForTest:$AllowInsecureLoopbackHttpForTest
+            }
+            catch {
+                throw 'The existing Creator credential target has an unknown format.'
+            }
+            [byte[]]$originalFileHash = Get-AnswerMeCreatorCredentialFileHash -LiteralPath $resolvedTargetPath
+
+            $sameKey = Test-AnswerMeCreatorCredentialSecureEqual `
+                -Left $originalCredential.Password `
+                -Right $CreatorKey
+            if ($originalCredential.UserName -ceq $normalizedApiBaseUrl -and $sameKey) {
+                return [PSCustomObject]@{
+                    ok = $true
+                    status = 'no-op'
+                    creatorId = $CreatorId
+                    targetChanged = $false
+                    backupCreated = $false
+                    rollbackStatus = 'not-required'
+                    networkCalled = $false
+                }
+            }
+        }
+    }
+    catch {
+        if ($_.Exception.Data.Contains('AnswerMeCode')) {
+            throw $_.Exception
+        }
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'credential-store-preflight-failed' `
+            -Stage 'preflight' `
+            -Message 'Creator credential preflight failed.')
+    }
+
+    $createdParent = $false
+    $temporaryPath = Join-Path $targetParent ('.answerme-{0}.tmp.clixml' -f [Guid]::NewGuid().ToString('N'))
+    $backupPath = if ($targetPreviouslyExisted) {
+        Join-Path $targetParent ('.answerme-{0}.backup.clixml' -f [Guid]::NewGuid().ToString('N'))
+    }
+    else {
+        $null
+    }
+    $rollbackTemporaryPath = Join-Path $targetParent ('.answerme-{0}.rollback.clixml' -f [Guid]::NewGuid().ToString('N'))
+    $backupCreated = $false
+    $targetChanged = $false
+    $preserveBackup = $false
+    $newCredential = $null
+    $roundTrip = $null
+    try {
+        if (-not (Test-Path -LiteralPath $targetParent -PathType Container)) {
+            [IO.Directory]::CreateDirectory($targetParent) | Out-Null
+            $createdParent = $true
+        }
+
+        $newCredential = [PSCredential]::new($normalizedApiBaseUrl, $CreatorKey)
+        Export-AnswerMeCreatorCredentialFile -Credential $newCredential -LiteralPath $temporaryPath
+        $roundTrip = Import-AnswerMeCreatorCredentialFile -LiteralPath $temporaryPath
+        if ($roundTrip -isnot [PSCredential] -or
+            $roundTrip.UserName -cne $normalizedApiBaseUrl -or
+            -not (Test-AnswerMeCreatorCredentialSecureEqual -Left $roundTrip.Password -Right $CreatorKey)) {
+            throw (New-AnswerMeCreatorCredentialStoreException `
+                -Code 'credential-write-verification-failed' `
+                -Stage 'install' `
+                -Message 'The staged Creator credential failed protected readback verification.')
+        }
+        $roundTrip = $null
+
+        $targetChanged = $true
+        Invoke-AnswerMeCreatorCredentialAtomicReplace `
+            -SourcePath $temporaryPath `
+            -TargetPath $resolvedTargetPath `
+            -BackupPath $backupPath `
+            -TargetExists $targetPreviouslyExisted
+        $backupCreated = $targetPreviouslyExisted -and (Test-Path -LiteralPath $backupPath -PathType Leaf)
+
+        try {
+            $roundTrip = Import-AnswerMeCreatorCredentialFile -LiteralPath $resolvedTargetPath
+            if ($roundTrip -isnot [PSCredential] -or
+                $roundTrip.UserName -cne $normalizedApiBaseUrl -or
+                -not (Test-AnswerMeCreatorCredentialSecureEqual -Left $roundTrip.Password -Right $CreatorKey)) {
+                throw 'The installed credential did not match the requested credential.'
+            }
+        }
+        catch {
+            $rollbackVerified = $false
+            try {
+                $backupCreated = $backupCreated -or (
+                    $targetPreviouslyExisted -and
+                    (Test-Path -LiteralPath $backupPath -PathType Leaf)
+                )
+                $rollbackVerified = Restore-AnswerMeCreatorCredentialTarget `
+                    -TargetPath $resolvedTargetPath `
+                    -BackupPath $backupPath `
+                    -OriginalFileHash $originalFileHash `
+                    -TargetPreviouslyExisted $targetPreviouslyExisted `
+                    -RollbackTemporaryPath $rollbackTemporaryPath
+            }
+            catch {
+                $rollbackVerified = $false
+            }
+            if (-not $rollbackVerified) {
+                $preserveBackup = $backupCreated
+                throw (New-AnswerMeCreatorCredentialStoreException `
+                    -Code 'rollback-unverified' `
+                    -Stage 'rollback' `
+                    -Message 'Creator credential rollback could not be verified.' `
+                    -TargetChanged $true `
+                    -BackupCreated $backupCreated `
+                    -RollbackStatus 'unverified')
+            }
+            throw (New-AnswerMeCreatorCredentialStoreException `
+                -Code 'credential-readback-failed' `
+                -Stage 'verify' `
+                -Message 'Installed Creator credential verification failed; the previous target was restored.' `
+                -TargetChanged $true `
+                -BackupCreated $backupCreated `
+                -RollbackStatus 'verified')
+        }
+
+        return [PSCustomObject]@{
+            ok = $true
+            status = 'installed'
+            creatorId = $CreatorId
+            targetChanged = $true
+            backupCreated = $backupCreated
+            rollbackStatus = 'not-required'
+            networkCalled = $false
+        }
+    }
+    catch {
+        if ($_.Exception.Data.Contains('AnswerMeCode')) {
+            throw $_.Exception
+        }
+
+        $backupCreated = $backupCreated -or (
+            $targetPreviouslyExisted -and
+            -not [string]::IsNullOrWhiteSpace($backupPath) -and
+            (Test-Path -LiteralPath $backupPath -PathType Leaf)
+        )
+        $rollbackVerified = $false
+        try {
+            if ($targetChanged) {
+                $rollbackVerified = Restore-AnswerMeCreatorCredentialTarget `
+                    -TargetPath $resolvedTargetPath `
+                    -BackupPath $backupPath `
+                    -OriginalFileHash $originalFileHash `
+                    -TargetPreviouslyExisted $targetPreviouslyExisted `
+                    -RollbackTemporaryPath $rollbackTemporaryPath
+            }
+            else {
+                $rollbackVerified = $true
+            }
+        }
+        catch {
+            $rollbackVerified = $false
+        }
+        if (-not $rollbackVerified) {
+            $preserveBackup = $backupCreated
+            throw (New-AnswerMeCreatorCredentialStoreException `
+                -Code 'rollback-unverified' `
+                -Stage 'rollback' `
+                -Message 'Creator credential rollback could not be verified.' `
+                -TargetChanged $targetChanged `
+                -BackupCreated $backupCreated `
+                -RollbackStatus 'unverified')
+        }
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'credential-install-failed' `
+            -Stage 'install' `
+            -Message 'Creator credential installation failed.' `
+            -TargetChanged $targetChanged `
+            -BackupCreated $backupCreated `
+            -RollbackStatus $(if ($targetChanged) { 'verified' } else { 'not-required' }))
+    }
+    finally {
+        $newCredential = $null
+        $roundTrip = $null
+        $originalCredential = $null
+        if ($null -ne $originalFileHash) {
+            Clear-AnswerMeSensitiveByteArray -Bytes $originalFileHash
+        }
+        foreach ($cleanupPath in @($temporaryPath, $rollbackTemporaryPath)) {
+            if (-not [string]::IsNullOrWhiteSpace($cleanupPath) -and
+                (Test-Path -LiteralPath $cleanupPath -PathType Leaf)) {
+                Remove-Item -LiteralPath $cleanupPath -Force -ErrorAction SilentlyContinue
+            }
+        }
+        if (-not $preserveBackup -and
+            -not [string]::IsNullOrWhiteSpace($backupPath) -and
+            (Test-Path -LiteralPath $backupPath -PathType Leaf)) {
+            Remove-Item -LiteralPath $backupPath -Force -ErrorAction SilentlyContinue
+        }
+        if ($createdParent -and (Test-Path -LiteralPath $targetParent -PathType Container)) {
+            try {
+                [IO.Directory]::Delete($targetParent, $false)
+            }
+            catch {
+                # Keep a non-empty directory; never remove unknown assets during cleanup.
+            }
+        }
+    }
+}