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

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

@@ -0,0 +1,447 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string]$HandoffCredentialPath,
+    [Parameter(Mandatory = $true)][string]$CreatorId,
+    [Parameter(Mandatory = $true)][string]$ApiBaseUrl,
+    [string]$TargetCredentialPath,
+    [switch]$VerifyRemote,
+    [switch]$AllowInsecureLoopbackHttpForTest,
+    [string]$CredentialStoreAdapterPath = (Join-Path $PSScriptRoot 'creator-credential-store.windows.ps1'),
+    [switch]$AllowTestAdapter
+)
+
+$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
+$httpSupport = Join-Path $PSScriptRoot 'windows-http.ps1'
+if (-not (Test-Path -LiteralPath $httpSupport -PathType Leaf)) {
+    throw 'The AnswerMe Windows HTTP helper is missing.'
+}
+. $httpSupport
+$networkCalled = $false
+$targetChanged = $false
+$backupCreated = $false
+$rollbackStatus = 'not-required'
+$handoffRemoved = $false
+$verifiedRemotely = $false
+$remoteValid = $null
+$remoteReason = $null
+$safeCreatorId = $null
+$handoffHash = $null
+$handoffCredential = $null
+$resolvedHandoffPath = $null
+$resolvedTargetPath = $null
+$cleanupQuarantinePath = $null
+$handoffQuarantined = $false
+
+function Write-AnswerMeCreatorCredentialDeployFailure {
+    param(
+        [Parameter(Mandatory = $true)][string]$Stage,
+        [Parameter(Mandatory = $true)][string]$Code,
+        [Parameter(Mandatory = $true)][string]$Message,
+        [Parameter(Mandatory = $true)][int]$ExitCode
+    )
+
+    [PSCustomObject]@{
+        ok = $false
+        status = 'failed'
+        stage = $Stage
+        code = $Code
+        message = $Message
+        creatorId = if ($VerifyRemote -and $remoteValid -ne $true) { $null } else { $safeCreatorId }
+        targetChanged = $targetChanged
+        backupCreated = $backupCreated
+        rollbackStatus = $rollbackStatus
+        handoffRemoved = $handoffRemoved
+        verifiedRemotely = $verifiedRemotely
+        valid = $remoteValid
+        reason = $remoteReason
+        networkCalled = $networkCalled
+    } | ConvertTo-Json -Compress
+    exit $ExitCode
+}
+
+function Get-AnswerMeCreatorCredentialDeployExitCode {
+    param([Parameter(Mandatory = $true)][string]$Stage)
+
+    switch ($Stage) {
+        'preflight' { return 2 }
+        'install' { return 3 }
+        'verify' { return 4 }
+        'cleanup' { return 5 }
+        'rollback' { return 6 }
+        default { return 3 }
+    }
+}
+
+function Get-AnswerMeCreatorCredentialDeployDataValue {
+    param(
+        [Parameter(Mandatory = $true)][Exception]$Exception,
+        [Parameter(Mandatory = $true)][string]$Name,
+        [AllowNull()][object]$Default
+    )
+
+    if ($Exception.Data.Contains($Name)) {
+        return $Exception.Data[$Name]
+    }
+    return $Default
+}
+
+function Test-AnswerMeCreatorCredentialDeployAllowedProperties {
+    param(
+        [Parameter(Mandatory = $true)][object]$Value,
+        [Parameter(Mandatory = $true)][string[]]$Allowed
+    )
+
+    $actual = @($Value.PSObject.Properties.Name)
+    return $actual.Count -eq $Allowed.Count -and
+        @($actual | Where-Object { $Allowed -cnotcontains $_ }).Count -eq 0
+}
+
+function Invoke-AnswerMeCreatorCredentialRemoteVerification {
+    param(
+        [Parameter(Mandatory = $true)][string]$NormalizedApiBaseUrl,
+        [Parameter(Mandatory = $true)][string]$ExpectedCreatorId,
+        [Parameter(Mandatory = $true)][PSCredential]$Credential
+    )
+
+    $plainKey = $null
+    try {
+        $plainKey = $Credential.GetNetworkCredential().Password
+        if ([string]::IsNullOrEmpty($plainKey)) {
+            throw 'The handoff credential is empty.'
+        }
+        $script:networkCalled = $true
+        $response = Invoke-AnswerMeWebRequest `
+            -Uri ($NormalizedApiBaseUrl + '/api/v1/creator-credentials/verify') `
+            -Method Get `
+            -Headers @{
+                Accept = 'application/json'
+                Authorization = "Bearer $plainKey"
+            } `
+            -TimeoutSec 30
+    }
+    catch {
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'creator-credential-verification-unavailable' `
+            -Stage 'verify' `
+            -Message 'Remote Creator credential verification was unavailable.')
+    }
+    finally {
+        $plainKey = $null
+    }
+
+    $cacheControl = ([string]$response.Headers['Cache-Control']).Trim()
+    try {
+        $body = $response.Content | ConvertFrom-Json
+    }
+    catch {
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'creator-credential-verification-invalid-response' `
+            -Stage 'verify' `
+            -Message 'Remote Creator credential verification returned an invalid response.')
+    }
+
+    if ([int]$response.StatusCode -eq 503) {
+        if ($cacheControl -cne 'no-store' -or
+            $body -isnot [PSCustomObject] -or
+            -not (Test-AnswerMeCreatorCredentialDeployAllowedProperties `
+                -Value $body `
+                -Allowed @('code', 'requestId')) -or
+            $body.code -isnot [string] -or
+            [string]$body.code -cne 'service_unavailable' -or
+            $body.requestId -isnot [string] -or
+            [string]::IsNullOrWhiteSpace([string]$body.requestId)) {
+            throw (New-AnswerMeCreatorCredentialStoreException `
+                -Code 'creator-credential-verification-invalid-response' `
+                -Stage 'verify' `
+                -Message 'Remote Creator credential verification returned an invalid response.')
+        }
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'creator-credential-verification-unavailable' `
+            -Stage 'verify' `
+            -Message 'Remote Creator credential verification was unavailable.')
+    }
+    if ([int]$response.StatusCode -ne 200) {
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'creator-credential-verification-unavailable' `
+            -Stage 'verify' `
+            -Message 'Remote Creator credential verification was unavailable.')
+    }
+    if ($cacheControl -cne 'no-store') {
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'creator-credential-verification-invalid-response' `
+            -Stage 'verify' `
+            -Message 'Remote Creator credential verification returned an invalid response.')
+    }
+    if ($body -isnot [PSCustomObject] -or
+        $body.valid -isnot [bool] -or
+        $body.requestId -isnot [string] -or
+        [string]::IsNullOrWhiteSpace($body.requestId)) {
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'creator-credential-verification-invalid-response' `
+            -Stage 'verify' `
+            -Message 'Remote Creator credential verification returned an invalid response.')
+    }
+
+    if ($body.valid) {
+        if (-not (Test-AnswerMeCreatorCredentialDeployAllowedProperties `
+                -Value $body `
+                -Allowed @('valid', 'creatorId', 'reason', 'requestId')) -or
+            $body.creatorId -isnot [string] -or
+            $body.reason -isnot [string] -or
+            [string]::IsNullOrWhiteSpace($body.creatorId) -or
+            $body.creatorId -cne $ExpectedCreatorId -or
+            $body.reason -cne 'active') {
+            throw (New-AnswerMeCreatorCredentialStoreException `
+                -Code 'creator-credential-verification-invalid-response' `
+                -Stage 'verify' `
+                -Message 'Remote Creator credential verification returned an invalid response.')
+        }
+        return [PSCustomObject]@{
+            creatorId = $body.creatorId
+            valid = $true
+            reason = 'active'
+        }
+    }
+
+    if (-not (Test-AnswerMeCreatorCredentialDeployAllowedProperties `
+            -Value $body `
+            -Allowed @('valid', 'reason', 'requestId')) -or
+        $body.reason -isnot [string] -or
+        $body.reason -cnotin @('invalid', 'idle_expired', 'max_lifetime_expired', 'abuse_revoked')) {
+        throw (New-AnswerMeCreatorCredentialStoreException `
+            -Code 'creator-credential-verification-invalid-response' `
+            -Stage 'verify' `
+            -Message 'Remote Creator credential verification returned an invalid response.')
+    }
+    return [PSCustomObject]@{
+        creatorId = $null
+        valid = $false
+        reason = $body.reason
+    }
+}
+
+try {
+    if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
+        throw 'The Creator credential deployment command requires Windows.'
+    }
+    $defaultAdapterPath = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot 'creator-credential-store.windows.ps1'))
+    $resolvedAdapterPath = [IO.Path]::GetFullPath($CredentialStoreAdapterPath)
+    if (-not $AllowTestAdapter -and
+        -not $resolvedAdapterPath.Equals($defaultAdapterPath, [StringComparison]::OrdinalIgnoreCase)) {
+        throw 'A non-default Credential Store adapter is allowed only for isolated tests.'
+    }
+    if (-not (Test-Path -LiteralPath $resolvedAdapterPath -PathType Leaf)) {
+        throw 'The Creator Credential Store adapter is unavailable.'
+    }
+    . $resolvedAdapterPath
+    foreach ($requiredFunction in @(
+        'Install-AnswerMeCreatorCredential',
+        'Resolve-AnswerMeCreatorCredentialApiBaseUrl',
+        'Get-AnswerMeDefaultCreatorCredentialPath',
+        'Get-AnswerMeCreatorCredentialFileHash',
+        'Test-AnswerMeCreatorCredentialBytesEqual',
+        'Test-AnswerMeCreatorCredentialSecureEqual',
+        'New-AnswerMeCreatorCredentialStoreException'
+    )) {
+        if (-not (Get-Command -Name $requiredFunction -CommandType Function -ErrorAction SilentlyContinue)) {
+            throw 'The Creator Credential Store adapter contract is incomplete.'
+        }
+    }
+
+    $safeCreatorId = $CreatorId.Trim()
+    if ([string]::IsNullOrWhiteSpace($safeCreatorId)) {
+        throw 'Creator ID is required.'
+    }
+    $normalizedApiBaseUrl = Resolve-AnswerMeCreatorCredentialApiBaseUrl `
+        -ApiBaseUrl $ApiBaseUrl `
+        -AllowInsecureLoopbackHttpForTest:$AllowInsecureLoopbackHttpForTest
+
+    $resolvedHandoffPath = [IO.Path]::GetFullPath($HandoffCredentialPath)
+    if ([IO.Path]::GetExtension($resolvedHandoffPath) -cne '.clixml' -or
+        -not (Test-Path -LiteralPath $resolvedHandoffPath -PathType Leaf)) {
+        throw 'The protected handoff credential is unavailable or has an unknown format.'
+    }
+    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 ($resolvedHandoffPath.Equals($resolvedTargetPath, [StringComparison]::OrdinalIgnoreCase)) {
+        throw 'The handoff and target credential files must be different.'
+    }
+    $handoffRoot = [IO.Path]::GetPathRoot($resolvedHandoffPath)
+    $targetRoot = [IO.Path]::GetPathRoot($resolvedTargetPath)
+    if ([string]::IsNullOrWhiteSpace($handoffRoot) -or
+        [string]::IsNullOrWhiteSpace($targetRoot) -or
+        -not $handoffRoot.Equals($targetRoot, [StringComparison]::OrdinalIgnoreCase)) {
+        throw 'The handoff and target credential files must be on the same volume.'
+    }
+
+    try {
+        $handoffCredential = Import-Clixml -LiteralPath $resolvedHandoffPath
+    }
+    catch {
+        throw 'The protected handoff credential cannot be read by this Windows account.'
+    }
+    if ($handoffCredential -isnot [PSCredential] -or
+        $handoffCredential.UserName -cne $safeCreatorId -or
+        $handoffCredential.Password.Length -eq 0) {
+        throw 'The protected handoff credential has an unknown format or account mismatch.'
+    }
+    [byte[]]$handoffHash = Get-AnswerMeCreatorCredentialFileHash -LiteralPath $resolvedHandoffPath
+}
+catch {
+    Write-AnswerMeCreatorCredentialDeployFailure `
+        -Stage 'preflight' `
+        -Code 'credential-deploy-preflight-failed' `
+        -Message 'Creator credential deployment preflight failed.' `
+        -ExitCode 2
+}
+
+if ($VerifyRemote) {
+    try {
+        $remoteVerification = Invoke-AnswerMeCreatorCredentialRemoteVerification `
+            -NormalizedApiBaseUrl $normalizedApiBaseUrl `
+            -ExpectedCreatorId $safeCreatorId `
+            -Credential $handoffCredential
+        $verifiedRemotely = $true
+        $remoteValid = [bool]$remoteVerification.valid
+        $remoteReason = [string]$remoteVerification.reason
+        if (-not $remoteValid) {
+            Write-AnswerMeCreatorCredentialDeployFailure `
+                -Stage 'verify' `
+                -Code 'creator-credential-invalid' `
+                -Message 'Remote verification rejected the Creator credential.' `
+                -ExitCode 4
+        }
+    }
+    catch {
+        $stage = [string](Get-AnswerMeCreatorCredentialDeployDataValue `
+            -Exception $_.Exception -Name 'AnswerMeStage' -Default 'verify')
+        $code = [string](Get-AnswerMeCreatorCredentialDeployDataValue `
+            -Exception $_.Exception -Name 'AnswerMeCode' -Default 'creator-credential-verification-failed')
+        Write-AnswerMeCreatorCredentialDeployFailure `
+            -Stage $stage `
+            -Code $code `
+            -Message 'Remote Creator credential verification failed.' `
+            -ExitCode 4
+    }
+}
+
+try {
+    $installResult = Install-AnswerMeCreatorCredential `
+        -CreatorKey $handoffCredential.Password `
+        -ApiBaseUrl $normalizedApiBaseUrl `
+        -CreatorId $safeCreatorId `
+        -TargetCredentialPath $resolvedTargetPath `
+        -AllowInsecureLoopbackHttpForTest:$AllowInsecureLoopbackHttpForTest
+    $targetChanged = [bool]$installResult.targetChanged
+    $backupCreated = [bool]$installResult.backupCreated
+    $rollbackStatus = [string]$installResult.rollbackStatus
+}
+catch {
+    $stage = [string](Get-AnswerMeCreatorCredentialDeployDataValue `
+        -Exception $_.Exception -Name 'AnswerMeStage' -Default 'install')
+    $code = [string](Get-AnswerMeCreatorCredentialDeployDataValue `
+        -Exception $_.Exception -Name 'AnswerMeCode' -Default 'credential-install-failed')
+    $targetChanged = [bool](Get-AnswerMeCreatorCredentialDeployDataValue `
+        -Exception $_.Exception -Name 'AnswerMeTargetChanged' -Default $false)
+    $backupCreated = [bool](Get-AnswerMeCreatorCredentialDeployDataValue `
+        -Exception $_.Exception -Name 'AnswerMeBackupCreated' -Default $false)
+    $rollbackStatus = [string](Get-AnswerMeCreatorCredentialDeployDataValue `
+        -Exception $_.Exception -Name 'AnswerMeRollbackStatus' -Default 'not-required')
+    Write-AnswerMeCreatorCredentialDeployFailure `
+        -Stage $stage `
+        -Code $code `
+        -Message 'Creator credential installation failed.' `
+        -ExitCode (Get-AnswerMeCreatorCredentialDeployExitCode -Stage $stage)
+}
+
+try {
+    if (-not (Test-Path -LiteralPath $resolvedHandoffPath -PathType Leaf)) {
+        throw 'The protected handoff credential changed before cleanup.'
+    }
+    $handoffParent = [IO.Path]::GetDirectoryName($resolvedHandoffPath)
+    $cleanupQuarantinePath = Join-Path $handoffParent ('.answerme-{0}.handoff-cleanup.clixml' -f [Guid]::NewGuid().ToString('N'))
+    [IO.File]::Move($resolvedHandoffPath, $cleanupQuarantinePath)
+    $handoffQuarantined = $true
+
+    [byte[]]$currentHandoffHash = Get-AnswerMeCreatorCredentialFileHash -LiteralPath $cleanupQuarantinePath
+    try {
+        if (-not (Test-AnswerMeCreatorCredentialBytesEqual -Left $handoffHash -Right $currentHandoffHash)) {
+            throw 'The protected handoff credential changed before cleanup.'
+        }
+    }
+    finally {
+        Clear-AnswerMeSensitiveByteArray -Bytes $currentHandoffHash
+    }
+    $cleanupCredential = Import-Clixml -LiteralPath $cleanupQuarantinePath
+    if ($cleanupCredential -isnot [PSCredential] -or
+        $cleanupCredential.UserName -cne $safeCreatorId -or
+        -not (Test-AnswerMeCreatorCredentialSecureEqual `
+            -Left $cleanupCredential.Password `
+            -Right $handoffCredential.Password)) {
+        throw 'The protected handoff credential changed before cleanup.'
+    }
+    $cleanupCredential = $null
+    [IO.File]::Delete($cleanupQuarantinePath)
+    if (Test-Path -LiteralPath $cleanupQuarantinePath) {
+        throw 'The protected handoff credential could not be removed.'
+    }
+    $handoffQuarantined = $false
+    $handoffRemoved = $true
+}
+catch {
+    if ($handoffQuarantined -and
+        -not [string]::IsNullOrWhiteSpace($cleanupQuarantinePath) -and
+        (Test-Path -LiteralPath $cleanupQuarantinePath -PathType Leaf) -and
+        -not (Test-Path -LiteralPath $resolvedHandoffPath)) {
+        try {
+            [IO.File]::Move($cleanupQuarantinePath, $resolvedHandoffPath)
+        }
+        catch {
+            # Preserve the quarantined asset when its original path cannot be restored safely.
+        }
+    }
+    Write-AnswerMeCreatorCredentialDeployFailure `
+        -Stage 'cleanup' `
+        -Code 'handoff-cleanup-failed' `
+        -Message 'The installed credential is protected, but exact handoff cleanup failed.' `
+        -ExitCode 5
+}
+finally {
+    $handoffCredential = $null
+    if ($null -ne $handoffHash) {
+        Clear-AnswerMeSensitiveByteArray -Bytes $handoffHash
+    }
+}
+
+[PSCustomObject]@{
+    ok = $true
+    status = [string]$installResult.status
+    stage = 'complete'
+    code = if ($installResult.status -ceq 'no-op') {
+        'credential-unchanged'
+    }
+    else {
+        'credential-deployed'
+    }
+    message = 'Creator credential deployment completed.'
+    creatorId = $safeCreatorId
+    targetChanged = $targetChanged
+    backupCreated = $backupCreated
+    rollbackStatus = $rollbackStatus
+    handoffRemoved = $handoffRemoved
+    verifiedRemotely = $verifiedRemotely
+    valid = $remoteValid
+    reason = $remoteReason
+    networkCalled = $networkCalled
+} | ConvertTo-Json -Compress
+exit 0