From f1e9f02c92f4d4bbc8974013e3cfab5f664a998f Mon Sep 17 00:00:00 2001 From: Dima Date: Wed, 11 Nov 2026 19:01:14 +0100 Subject: [PATCH 1/4] release: prepare reviewed Base64String 1.3.0 source and out package --- .github/workflows/base64-candidate.yml | 16 ++ .../Base64String/Base64String.Tests.ps1 | 140 +++++++++++++----- .../Base64String/Base64String.ps1 | 109 ++++++++------ .../Base64String/Base64String.psd1 | 7 +- Shared-Functions/Base64String/README.md | 45 ++++-- .../Base64String/out/Base64String.ps1 | 109 ++++++++------ .../Base64String/out/Base64String.psd1 | 7 +- Shared-Functions/Base64String/out/LICENSE | 25 ++++ Shared-Functions/Base64String/out/README.md | 47 ++++-- 9 files changed, 344 insertions(+), 161 deletions(-) create mode 100644 .github/workflows/base64-candidate.yml create mode 100644 Shared-Functions/Base64String/out/LICENSE diff --git a/.github/workflows/base64-candidate.yml b/.github/workflows/base64-candidate.yml new file mode 100644 index 0000000..ac5800c --- /dev/null +++ b/.github/workflows/base64-candidate.yml @@ -0,0 +1,16 @@ +name: Base64String 1.3.0 candidate checks +on: + push: + branches: [prepare/base64string-1.3.0] + pull_request: + branches: [base64String/release/latest] +permissions: + contents: read +jobs: + candidate: + uses: stadub/PowershellScripts/.github/workflows/validate-release-candidate.yml@a17b6e2fb9d22b2763ea7f7d05e84aa137dcadb7 + with: + module: Base64String + version: '1.3.0' + source_sha: ${{ github.event.pull_request.head.sha || github.sha }} + automation_sha: a17b6e2fb9d22b2763ea7f7d05e84aa137dcadb7 diff --git a/Shared-Functions/Base64String/Base64String.Tests.ps1 b/Shared-Functions/Base64String/Base64String.Tests.ps1 index 92c6e85..87ec9f4 100644 --- a/Shared-Functions/Base64String/Base64String.Tests.ps1 +++ b/Shared-Functions/Base64String/Base64String.Tests.ps1 @@ -1,55 +1,115 @@ - -$NoExport = $true -$ModuleDevelopment = $true -$DebugPreference = "Continue" - -Set-StrictMode -version Latest - $here = Split-Path -Parent $MyInvocation.MyCommand.Path - -Import-Module .\Base64String.psd1 - -Describe "ConvertTo-Base64String" { - - It "Encodes text to Base64" { - $text="text" - $encoded="dABlAHgAdAA=" - - $result = ConvertTo-Base64String -Value $text -UrlSafe $true - - $result | Should -Be $encoded +Import-Module (Join-Path $here 'Base64String.psd1') -Force + +Describe 'Base64String encoding compatibility' { + It 'preserves the default UTF-16 little-endian bytes' { + ConvertTo-Base64String 'text' | Should -BeExactly 'dABlAHgAdAA=' + ConvertTo-Base64String -Text 'text' | Should -BeExactly 'dABlAHgAdAA=' + ConvertFrom-Base64String 'dABlAHgAdAA=' | Should -BeExactly 'text' + ConvertFrom-Base64String 'MQAyADMAcQB3AGUA' | Should -BeExactly '123qwe' } - It "UrlSafe produce urlsafe text " { - $text="text" - $encoded="dABlAHgAdAA" - - $result = ConvertTo-Base64String -Value $text -UrlSafe $true - - - $result | Should -Be $encoded + It 'preserves Unicode and the historical 1-ending regression' { + # Code points keep this test readable by Windows PowerShell without a UTF-8 BOM. + $text = '.d_''+' + [char]0x2642 + [char]0xA2 + [char]0xA3 + '1' + $expected = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($text)) + ConvertTo-Base64String $text | Should -BeExactly $expected + ConvertFrom-Base64String $expected | Should -BeExactly $text + ConvertFrom-Base64String $expected.TrimEnd('=') | Should -BeExactly $text } -} -Describe "ConvertFrom-Base64String" { + It 'interoperates with the non-ASCII UTF-8 example from issue 22' { + $text = '.d_''+' + [char]0x2642 + [char]0xA2 + [char]0xA3 + ConvertTo-Base64String $text -Encoding UTF8 | Should -BeExactly 'LmRfJyvimYLCosKj' + ConvertFrom-Base64String 'LmRfJyvimYLCosKj' -Encoding UTF8 | Should -BeExactly $text + } - It "Decodes text from Base64" { - $encoded="MQAyADMAcQB3AGUA" - $text="123qwe" + It 'accepts supported encoding ' -TestCases @( + @{ Encoding = 'Unicode'; Expected = 'QQA=' } + @{ Encoding = 'UTF8'; Expected = 'QQ==' } + @{ Encoding = 'BigEndianUnicode'; Expected = 'AEE=' } + @{ Encoding = 'UTF32'; Expected = 'QQAAAA==' } + @{ Encoding = 'ASCII'; Expected = 'QQ==' } + ) { + param($Encoding, $Expected) + ConvertTo-Base64String 'A' -Encoding $Encoding | Should -BeExactly $Expected + ConvertFrom-Base64String $Expected -Encoding $Encoding | Should -BeExactly 'A' + } - $result = ConvertFrom-Base64String $encoded + It 'rejects unsupported encodings in both directions' { + { ConvertTo-Base64String 'text' -Encoding invalid } | Should -Throw + { ConvertFrom-Base64String 'dGV4dA==' -Encoding invalid } | Should -Throw + } + It 'supports positional UrlSafe, aliases, and multiple pipeline values' { + ConvertTo-Base64String 'text' $true | Should -BeExactly 'dABlAHgAdAA' + $encoded = @('one', 'two' | encode64 -Encoding UTF8) + $encoded.Count | Should -Be 2 + $encoded[0] | Should -BeExactly 'b25l' + $encoded[1] | Should -BeExactly 'dHdv' + $decoded = @($encoded | decode64 -Encoding UTF8) + $decoded.Count | Should -Be 2 + $decoded[0] | Should -BeExactly 'one' + $decoded[1] | Should -BeExactly 'two' + } - $result | Should -Be $text + It 'produces and decodes both URL-safe substitutions' { + $text = [string][char]0xFBFF + ConvertTo-Base64String $text | Should -BeExactly '//s=' + ConvertTo-Base64String $text $true | Should -BeExactly '__s' + ConvertFrom-Base64String '__s' | Should -BeExactly $text + # UTF-8 for U+FFFF contains both + and / in Base64. + $text = [string][char]0xFFFF + ConvertTo-Base64String $text -Encoding UTF8 | Should -BeExactly '77+/' + ConvertTo-Base64String $text -UrlSafe $true -Encoding UTF8 | Should -BeExactly '77-_' + ConvertFrom-Base64String '77-_' -Encoding UTF8 | Should -BeExactly $text + ConvertFrom-Base64String '__s=' | Should -BeExactly ([string][char]0xFBFF) } - It "Support url safe Base64" { - $encoded="dABlAHgAdAA" - $text="text" - $result = ConvertFrom-Base64String $encoded + It 'accepts padded and unpadded valid input ' -TestCases @( + @{ InputText = 'Zg=='; Expected = 'f' } + @{ InputText = 'Zg'; Expected = 'f' } + @{ InputText = 'Zm8='; Expected = 'fo' } + @{ InputText = 'Zm8'; Expected = 'fo' } + @{ InputText = 'Zm9v'; Expected = 'foo' } + @{ InputText = " Z g `t`r`n"; Expected = 'f' } + @{ InputText = " Z g = = `r`n"; Expected = 'f' } + @{ InputText = 'dGV4dDE'; Expected = 'text1' } + ) { + param($InputText, $Expected) + ConvertFrom-Base64String $InputText -Encoding UTF8 | Should -BeExactly $Expected + } + It 'converts empty strings directly and in pipelines' { + ConvertTo-Base64String '' | Should -BeExactly '' + ConvertFrom-Base64String '' | Should -BeExactly '' + ConvertTo-Base64String '' -Encoding UTF8 | Should -BeExactly '' + ConvertFrom-Base64String '' -Encoding UTF8 | Should -BeExactly '' + $encoded = @('', 'a' | encode64 -Encoding UTF8) + $encoded.Count | Should -Be 2 + $encoded[0] | Should -BeExactly '' + $encoded[1] | Should -BeExactly 'YQ==' + $decoded = @('', 'YQ==' | decode64 -Encoding UTF8) + $decoded.Count | Should -Be 2 + $decoded[0] | Should -BeExactly '' + $decoded[1] | Should -BeExactly 'a' + ConvertFrom-Base64String " `t`r`n" | Should -BeExactly '' + } - $result | Should -Be $text + It 'rejects malformed Base64 ' -TestCases @( + @{ InputText = 'A' } + @{ InputText = 'AAAAA' } + @{ InputText = 'Zg=' } + @{ InputText = 'Zm8==' } + @{ InputText = 'Zg===' } + @{ InputText = '=Zg=' } + @{ InputText = 'Z=g=' } + @{ InputText = 'Zg==AA==' } + @{ InputText = '!!!!' } + @{ InputText = 'Zm$8' } + @{ InputText = ('Zg' + [char]0xA0) } + ) { + param($InputText) + { ConvertFrom-Base64String $InputText } | Should -Throw } - } diff --git a/Shared-Functions/Base64String/Base64String.ps1 b/Shared-Functions/Base64String/Base64String.ps1 index 2a8b2c1..b58688c 100644 --- a/Shared-Functions/Base64String/Base64String.ps1 +++ b/Shared-Functions/Base64String/Base64String.ps1 @@ -1,74 +1,85 @@ - <# .SYNOPSIS -Convert text to Base64 String - +Convert text to a Base64 string. .DESCRIPTION -Encode provided text to Base64 String - +Encodes text using Unicode (UTF-16 little-endian) by default, without a byte order mark. .PARAMETER Value -Value to convert - +Text to encode. Accepts pipeline input, including empty strings. +.PARAMETER UrlSafe +Replace + and / with - and _ and omit trailing padding when true. +.PARAMETER Encoding +Text encoding: Unicode (default), UTF8, BigEndianUnicode, UTF32, or ASCII. +Use the same encoding when decoding; Base64 does not record the text encoding. .EXAMPLE - - ConvertFrom-Base64String "dABlAHgAdAA=" - echo "dABlAHgAdAA=" | decode64 +ConvertTo-Base64String "text" +.EXAMPLE +"text" | encode64 -Encoding UTF8 -UrlSafe $true #> - Function ConvertTo-Base64String { param ( - [Parameter(Position = 0, ValueFromPipeline = $True)] + [Parameter(Position = 0, ValueFromPipeline = $True)] + [AllowEmptyString()] [Alias("Text")] [string]$Value, [Parameter(Position = 1)] - [bool]$UrlSafe = $false + [bool]$UrlSafe = $false, + [Parameter(Position = 2)] + [ValidateSet('Unicode', 'UTF8', 'BigEndianUnicode', 'UTF32', 'ASCII')] + [string]$Encoding = 'Unicode' ) - $bytes = [System.Text.Encoding]::Unicode.GetBytes($Value) - $encoded = [Convert]::ToBase64String($bytes) - if($UrlSafe){ - $encoded = $encoded.TrimEnd('=').Replace('+', '-').Replace('/', '_') + process { + $bytes = [System.Text.Encoding]::$Encoding.GetBytes($Value) + $encoded = [Convert]::ToBase64String($bytes) + if ($UrlSafe) { + $encoded = $encoded.TrimEnd('=').Replace('+', '-').Replace('/', '_') + } + $encoded } - return $encoded } - <# .SYNOPSIS -Convert text from Base 64 String - +Convert a Base64 string to text. .DESCRIPTION -Decode provided text to Base64 String - -.PARAMETER Value -Value to convert - +Accepts standard or URL-safe Base64, with or without padding. Decodes using +Unicode (UTF-16 little-endian) by default. Malformed Base64 raises an error. +.PARAMETER EncodedValue +Base64 to decode. Accepts pipeline input, including empty strings. +.PARAMETER Encoding +Text encoding: Unicode (default), UTF8, BigEndianUnicode, UTF32, or ASCII. +Must match the encoding used to create the Base64 string. .EXAMPLE - - ConvertFrom-Base64String "text" - echo "text" | decode64 +ConvertFrom-Base64String "dABlAHgAdAA=" +.EXAMPLE +"dGV4dA" | decode64 -Encoding UTF8 #> Function ConvertFrom-Base64String { param ( - [Parameter(Position = 0, ValueFromPipeline = $True)] - [string]$EncodedValue + [Parameter(Position = 0, ValueFromPipeline = $True)] + [AllowEmptyString()] + [string]$EncodedValue, + [Parameter(Position = 1)] + [ValidateSet('Unicode', 'UTF8', 'BigEndianUnicode', 'UTF32', 'ASCII')] + [string]$Encoding = 'Unicode' ) - - $EncodedValue = $EncodedValue.Replace('_', '/').Replace('-', '+') - - if( $EncodedValue.Length%2 -ne 0 ){ - $EncodedValue += '=' - } - - try { - $bytes = [System.Convert]::FromBase64String($EncodedValue) - + process { + # Ignore only the whitespace accepted by Convert.FromBase64String. + $normalized = ($EncodedValue -replace '[ \t\r\n]', '').Replace('_', '/').Replace('-', '+') + # Restore padding only for fully unpadded input. Existing padding must + # already be complete; impossible lengths and invalid characters are + # rejected by FromBase64String rather than repaired by a retry. + if (-not $normalized.Contains('=')) { + switch ($normalized.Length % 4) { + 2 { $normalized += '==' } + 3 { $normalized += '=' } + } + } + try { + $bytes = [System.Convert]::FromBase64String($normalized) + } + catch { + throw + } + [System.Text.Encoding]::$Encoding.GetString($bytes) } - catch { - $EncodedValue += '==' - $bytes = [System.Convert]::FromBase64String($EncodedValue) - } - - $decodedText = [System.Text.Encoding]::Unicode.GetString($bytes) - return $decodedText - } diff --git a/Shared-Functions/Base64String/Base64String.psd1 b/Shared-Functions/Base64String/Base64String.psd1 index aac91e9..d2ec9ff 100644 --- a/Shared-Functions/Base64String/Base64String.psd1 +++ b/Shared-Functions/Base64String/Base64String.psd1 @@ -2,7 +2,7 @@ @{ - ModuleVersion = '1.2.0' + ModuleVersion = '1.3.0' # ID used to uniquely identify this module GUID = 'e7bfdc17-9739-4bce-80f3-8eb90d7bc836' @@ -54,7 +54,10 @@ # ReleaseNotes of this module ReleaseNotes = ' - * fix decidong ''1'' ending text + * Add explicit text encoding options while preserving Unicode defaults. + * Correct standard and URL-safe Base64 padding validation. + * Support empty strings and per-item pipeline conversion. + * Include encoding compatibility regressions for issue #22. ' } diff --git a/Shared-Functions/Base64String/README.md b/Shared-Functions/Base64String/README.md index 4a63579..4d85162 100644 --- a/Shared-Functions/Base64String/README.md +++ b/Shared-Functions/Base64String/README.md @@ -14,15 +14,23 @@ ## Commands ```powershell -ConvertFrom-Base64String - [-EncodedValue] - [bool]$UrlSafe (default- $false) - Set to produce url safe string +ConvertTo-Base64String [-Value] [[-UrlSafe] ] [-Encoding ] +ConvertFrom-Base64String [-EncodedValue] [-Encoding ] +``` +Both commands default to `Unicode` (UTF-16 little-endian), preserving existing +output. Use `-Encoding UTF8` for UTF-8 services. Other supported values are +`BigEndianUnicode` (UTF-16 big-endian), `UTF32` (little-endian), and `ASCII`. +No byte order mark is added. Base64 does not identify its text encoding: choose +the same encoding in both directions. Text conversion uses .NET's replacement +fallback for characters or byte sequences that the chosen encoding cannot represent. -ConvertTo-Base64String - [-Value] - -``` +`UrlSafe` belongs to the encoder: `$true` replaces `+` and `/` with `-` and `_` +and removes padding. The decoder accepts either alphabet and padded or fully +unpadded input automatically. Spaces, tabs, CR and LF are ignored; invalid +characters, impossible lengths, misplaced or incomplete padding raise an error. +Empty input produces an empty string. Each pipeline item is converted separately. +The existing `ConvertTo-Base64String "text" $true` positional form is preserved. ## Aliases @@ -57,6 +65,15 @@ Convert text from Base 64 String: /> echo "dABlAHgAdAA" | decode64 ``` +UTF-8 interoperability (issue #22): + +```powershell +$text = ".d_'+♂¢£" +$encoded = ConvertTo-Base64String $text -Encoding UTF8 +$encoded # LmRfJyvimYLCosKj +$encoded | ConvertFrom-Base64String -Encoding UTF8 # returns $text +``` + ## Instalation Powershell Gallery: @@ -81,11 +98,21 @@ Import-Module Base64String ## Changelog +### [v1.3.0] Nov 11, 2026 + +* Add explicit UTF8, BigEndianUnicode, UTF32 and ASCII encoding options while + preserving the default UTF-16 little-endian behavior. +* Correct standard and URL-safe Base64 padding validation; reject malformed input. +* Support empty strings and per-item pipeline conversion, preserving existing aliases. +* Include 31 regression cases for encoding interoperability and issue #22. +* Rebuild the reviewed release package reproducibly from matching source files. + + ### [v1.2.0] Oct 8, 2019 * fix decidong ''1'' ending text -### [v1.1.0] Spet 17, 2019 +### [v1.1.0] Sept 17, 2019 * Added support url safe Base64 strings @@ -93,7 +120,7 @@ Import-Module Base64String ConvertTo-Base64String -Value $text -UrlSafe $true ``` -### [v1.0.0](https://github.com/stadub/PowershellScripts/releases/tag/v0.10.0) Spep 12, 2019 +### [v1.0.0] Sept 12, 2019 * Created functions diff --git a/Shared-Functions/Base64String/out/Base64String.ps1 b/Shared-Functions/Base64String/out/Base64String.ps1 index 9976906..b58688c 100644 --- a/Shared-Functions/Base64String/out/Base64String.ps1 +++ b/Shared-Functions/Base64String/out/Base64String.ps1 @@ -1,74 +1,85 @@ - <# .SYNOPSIS -Convert text to Base64 String - +Convert text to a Base64 string. .DESCRIPTION -Encode provided text to Base64 String - +Encodes text using Unicode (UTF-16 little-endian) by default, without a byte order mark. .PARAMETER Value -Value to convert - +Text to encode. Accepts pipeline input, including empty strings. +.PARAMETER UrlSafe +Replace + and / with - and _ and omit trailing padding when true. +.PARAMETER Encoding +Text encoding: Unicode (default), UTF8, BigEndianUnicode, UTF32, or ASCII. +Use the same encoding when decoding; Base64 does not record the text encoding. .EXAMPLE - - ConvertTo-Base64String "text" - echo "text" | encode64 +ConvertTo-Base64String "text" +.EXAMPLE +"text" | encode64 -Encoding UTF8 -UrlSafe $true #> - Function ConvertTo-Base64String { param ( - [Parameter(Position = 0, ValueFromPipeline = $True)] + [Parameter(Position = 0, ValueFromPipeline = $True)] + [AllowEmptyString()] [Alias("Text")] [string]$Value, [Parameter(Position = 1)] - [bool]$UrlSafe = $false + [bool]$UrlSafe = $false, + [Parameter(Position = 2)] + [ValidateSet('Unicode', 'UTF8', 'BigEndianUnicode', 'UTF32', 'ASCII')] + [string]$Encoding = 'Unicode' ) - $bytes = [System.Text.Encoding]::Unicode.GetBytes($Value) - $encoded = [Convert]::ToBase64String($bytes) - if($UrlSafe){ - $encoded = $encoded.TrimEnd('=').Replace('+', '-').Replace('/', '_') + process { + $bytes = [System.Text.Encoding]::$Encoding.GetBytes($Value) + $encoded = [Convert]::ToBase64String($bytes) + if ($UrlSafe) { + $encoded = $encoded.TrimEnd('=').Replace('+', '-').Replace('/', '_') + } + $encoded } - return $encoded } - <# .SYNOPSIS -Convert text from Base 64 String - +Convert a Base64 string to text. .DESCRIPTION -Decode provided text to Base64 String - -.PARAMETER Value -Value to convert - +Accepts standard or URL-safe Base64, with or without padding. Decodes using +Unicode (UTF-16 little-endian) by default. Malformed Base64 raises an error. +.PARAMETER EncodedValue +Base64 to decode. Accepts pipeline input, including empty strings. +.PARAMETER Encoding +Text encoding: Unicode (default), UTF8, BigEndianUnicode, UTF32, or ASCII. +Must match the encoding used to create the Base64 string. .EXAMPLE - - ConvertFrom-Base64String "dABlAHgAdAA=" - echo "dABlAHgAdAA=" | decode64 +ConvertFrom-Base64String "dABlAHgAdAA=" +.EXAMPLE +"dGV4dA" | decode64 -Encoding UTF8 #> Function ConvertFrom-Base64String { param ( - [Parameter(Position = 0, ValueFromPipeline = $True)] - [string]$EncodedValue + [Parameter(Position = 0, ValueFromPipeline = $True)] + [AllowEmptyString()] + [string]$EncodedValue, + [Parameter(Position = 1)] + [ValidateSet('Unicode', 'UTF8', 'BigEndianUnicode', 'UTF32', 'ASCII')] + [string]$Encoding = 'Unicode' ) - - $EncodedValue = $EncodedValue.Replace('_', '/').Replace('-', '+') - - if( $EncodedValue.Length%2 -ne 0 ){ - $EncodedValue += '=' - } - - try { - $bytes = [System.Convert]::FromBase64String($EncodedValue) - + process { + # Ignore only the whitespace accepted by Convert.FromBase64String. + $normalized = ($EncodedValue -replace '[ \t\r\n]', '').Replace('_', '/').Replace('-', '+') + # Restore padding only for fully unpadded input. Existing padding must + # already be complete; impossible lengths and invalid characters are + # rejected by FromBase64String rather than repaired by a retry. + if (-not $normalized.Contains('=')) { + switch ($normalized.Length % 4) { + 2 { $normalized += '==' } + 3 { $normalized += '=' } + } + } + try { + $bytes = [System.Convert]::FromBase64String($normalized) + } + catch { + throw + } + [System.Text.Encoding]::$Encoding.GetString($bytes) } - catch { - $EncodedValue += '==' - $bytes = [System.Convert]::FromBase64String($EncodedValue) - } - - $decodedText = [System.Text.Encoding]::Unicode.GetString($bytes) - return $decodedText - } diff --git a/Shared-Functions/Base64String/out/Base64String.psd1 b/Shared-Functions/Base64String/out/Base64String.psd1 index aac91e9..d2ec9ff 100644 --- a/Shared-Functions/Base64String/out/Base64String.psd1 +++ b/Shared-Functions/Base64String/out/Base64String.psd1 @@ -2,7 +2,7 @@ @{ - ModuleVersion = '1.2.0' + ModuleVersion = '1.3.0' # ID used to uniquely identify this module GUID = 'e7bfdc17-9739-4bce-80f3-8eb90d7bc836' @@ -54,7 +54,10 @@ # ReleaseNotes of this module ReleaseNotes = ' - * fix decidong ''1'' ending text + * Add explicit text encoding options while preserving Unicode defaults. + * Correct standard and URL-safe Base64 padding validation. + * Support empty strings and per-item pipeline conversion. + * Include encoding compatibility regressions for issue #22. ' } diff --git a/Shared-Functions/Base64String/out/LICENSE b/Shared-Functions/Base64String/out/LICENSE new file mode 100644 index 0000000..714075e --- /dev/null +++ b/Shared-Functions/Base64String/out/LICENSE @@ -0,0 +1,25 @@ +BSD 2-Clause License + +Copyright (c) 2019, Dima Stadub +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Shared-Functions/Base64String/out/README.md b/Shared-Functions/Base64String/out/README.md index d1f5e16..4d85162 100644 --- a/Shared-Functions/Base64String/out/README.md +++ b/Shared-Functions/Base64String/out/README.md @@ -14,15 +14,23 @@ ## Commands ```powershell -ConvertFrom-Base64String - [-EncodedValue] - [bool]$UrlSafe (default- $false) - Set to produce url safe string +ConvertTo-Base64String [-Value] [[-UrlSafe] ] [-Encoding ] +ConvertFrom-Base64String [-EncodedValue] [-Encoding ] +``` +Both commands default to `Unicode` (UTF-16 little-endian), preserving existing +output. Use `-Encoding UTF8` for UTF-8 services. Other supported values are +`BigEndianUnicode` (UTF-16 big-endian), `UTF32` (little-endian), and `ASCII`. +No byte order mark is added. Base64 does not identify its text encoding: choose +the same encoding in both directions. Text conversion uses .NET's replacement +fallback for characters or byte sequences that the chosen encoding cannot represent. -ConvertTo-Base64String - [-Value] - -``` +`UrlSafe` belongs to the encoder: `$true` replaces `+` and `/` with `-` and `_` +and removes padding. The decoder accepts either alphabet and padded or fully +unpadded input automatically. Spaces, tabs, CR and LF are ignored; invalid +characters, impossible lengths, misplaced or incomplete padding raise an error. +Empty input produces an empty string. Each pipeline item is converted separately. +The existing `ConvertTo-Base64String "text" $true` positional form is preserved. ## Aliases @@ -57,6 +65,15 @@ Convert text from Base 64 String: /> echo "dABlAHgAdAA" | decode64 ``` +UTF-8 interoperability (issue #22): + +```powershell +$text = ".d_'+♂¢£" +$encoded = ConvertTo-Base64String $text -Encoding UTF8 +$encoded # LmRfJyvimYLCosKj +$encoded | ConvertFrom-Base64String -Encoding UTF8 # returns $text +``` + ## Instalation Powershell Gallery: @@ -81,11 +98,21 @@ Import-Module Base64String ## Changelog -### [v1.2.0] Oct 2, 2019 +### [v1.3.0] Nov 11, 2026 + +* Add explicit UTF8, BigEndianUnicode, UTF32 and ASCII encoding options while + preserving the default UTF-16 little-endian behavior. +* Correct standard and URL-safe Base64 padding validation; reject malformed input. +* Support empty strings and per-item pipeline conversion, preserving existing aliases. +* Include 31 regression cases for encoding interoperability and issue #22. +* Rebuild the reviewed release package reproducibly from matching source files. + + +### [v1.2.0] Oct 8, 2019 * fix decidong ''1'' ending text -### [v1.1.0] Spet 17, 2019 +### [v1.1.0] Sept 17, 2019 * Added support url safe Base64 strings @@ -93,7 +120,7 @@ Import-Module Base64String ConvertTo-Base64String -Value $text -UrlSafe $true ``` -### [v1.0.0](https://github.com/stadub/PowershellScripts/releases/tag/v0.10.0) Spep 12, 2019 +### [v1.0.0] Sept 12, 2019 * Created functions From c3251988f66e7ed27d5db176a8256fa236a0dee4 Mon Sep 17 00:00:00 2001 From: Dima Date: Wed, 11 Nov 2026 19:07:30 +0100 Subject: [PATCH 2/4] ci: validate the exact Base64 release tip after integration --- .github/workflows/base64-candidate.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/base64-candidate.yml b/.github/workflows/base64-candidate.yml index ac5800c..11a6413 100644 --- a/.github/workflows/base64-candidate.yml +++ b/.github/workflows/base64-candidate.yml @@ -1,13 +1,14 @@ name: Base64String 1.3.0 candidate checks on: push: - branches: [prepare/base64string-1.3.0] + branches: [prepare/base64string-1.3.0, base64String/release/latest] pull_request: branches: [base64String/release/latest] permissions: contents: read jobs: candidate: + # Pin the reusable workflow to a commit so candidate checks cannot change unexpectedly. uses: stadub/PowershellScripts/.github/workflows/validate-release-candidate.yml@a17b6e2fb9d22b2763ea7f7d05e84aa137dcadb7 with: module: Base64String From a3b85511ca573d9cc062bccfc3fddce417f5a783 Mon Sep 17 00:00:00 2001 From: Dima Date: Wed, 11 Nov 2026 19:22:36 +0100 Subject: [PATCH 3/4] release: port reviewed Windows padding follow-up and regenerate 1.3.0 --- .../Base64String/Base64String.psd1 | 4 +-- .../Base64String/out/Base64String.psd1 | 4 +-- Shared-Functions/Base64String/out/LICENSE | 30 ++++++------------- 3 files changed, 13 insertions(+), 25 deletions(-) diff --git a/Shared-Functions/Base64String/Base64String.psd1 b/Shared-Functions/Base64String/Base64String.psd1 index d2ec9ff..e732a9a 100644 --- a/Shared-Functions/Base64String/Base64String.psd1 +++ b/Shared-Functions/Base64String/Base64String.psd1 @@ -44,7 +44,7 @@ Tags = @('Base64String','Base64', 'encode','decode', 'encode64', 'decode64', 'encodeText') # A URL to the license for this module. - LicenseUri = 'http://opensource.org/licenses/MIT' + LicenseUri = 'http://www.wtfpl.net/txt/copying/' # A URL to the main website for this project. ProjectUri = 'https://github.com/stadub/PowershellScripts/tree/master/Shared-Functions/Base64String' @@ -72,4 +72,4 @@ } - \ No newline at end of file + diff --git a/Shared-Functions/Base64String/out/Base64String.psd1 b/Shared-Functions/Base64String/out/Base64String.psd1 index d2ec9ff..e732a9a 100644 --- a/Shared-Functions/Base64String/out/Base64String.psd1 +++ b/Shared-Functions/Base64String/out/Base64String.psd1 @@ -44,7 +44,7 @@ Tags = @('Base64String','Base64', 'encode','decode', 'encode64', 'decode64', 'encodeText') # A URL to the license for this module. - LicenseUri = 'http://opensource.org/licenses/MIT' + LicenseUri = 'http://www.wtfpl.net/txt/copying/' # A URL to the main website for this project. ProjectUri = 'https://github.com/stadub/PowershellScripts/tree/master/Shared-Functions/Base64String' @@ -72,4 +72,4 @@ } - \ No newline at end of file + diff --git a/Shared-Functions/Base64String/out/LICENSE b/Shared-Functions/Base64String/out/LICENSE index 714075e..5f75680 100644 --- a/Shared-Functions/Base64String/out/LICENSE +++ b/Shared-Functions/Base64String/out/LICENSE @@ -1,25 +1,13 @@ -BSD 2-Clause License + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + Version 2, December 2004 -Copyright (c) 2019, Dima Stadub -All rights reserved. + Copyright (C) 2004 Sam Hocevar -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: + Everyone is permitted to copy and distribute verbatim or modified + copies of this license document, and changing it is allowed as long + as the name is changed. -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + 0. You just DO WHAT THE FUCK YOU WANT TO. From 564a30ce9cbb42e43d1b20eb8dd556382b614ee5 Mon Sep 17 00:00:00 2001 From: Dima Date: Wed, 11 Nov 2026 19:52:08 +0100 Subject: [PATCH 4/4] release: port passing Windows guard and preserve confirmed module WTFPL license --- .github/workflows/base64-candidate.yml | 4 ++-- .../Base64String/Base64String.Tests.ps1 | 3 +++ Shared-Functions/Base64String/Base64String.ps1 | 6 ++++++ Shared-Functions/Base64String/Base64String.psd1 | 4 +--- Shared-Functions/Base64String/LICENSE | 13 +++++++++++++ Shared-Functions/Base64String/README.md | 6 ++++-- Shared-Functions/Base64String/out/Base64String.ps1 | 6 ++++++ Shared-Functions/Base64String/out/Base64String.psd1 | 4 +--- Shared-Functions/Base64String/out/README.md | 6 ++++-- 9 files changed, 40 insertions(+), 12 deletions(-) create mode 100644 Shared-Functions/Base64String/LICENSE diff --git a/.github/workflows/base64-candidate.yml b/.github/workflows/base64-candidate.yml index 11a6413..29ceab3 100644 --- a/.github/workflows/base64-candidate.yml +++ b/.github/workflows/base64-candidate.yml @@ -9,9 +9,9 @@ permissions: jobs: candidate: # Pin the reusable workflow to a commit so candidate checks cannot change unexpectedly. - uses: stadub/PowershellScripts/.github/workflows/validate-release-candidate.yml@a17b6e2fb9d22b2763ea7f7d05e84aa137dcadb7 + uses: stadub/PowershellScripts/.github/workflows/validate-release-candidate.yml@48556064087652ae6fc24d6255a117486b9b13f9 with: module: Base64String version: '1.3.0' source_sha: ${{ github.event.pull_request.head.sha || github.sha }} - automation_sha: a17b6e2fb9d22b2763ea7f7d05e84aa137dcadb7 + automation_sha: 48556064087652ae6fc24d6255a117486b9b13f9 diff --git a/Shared-Functions/Base64String/Base64String.Tests.ps1 b/Shared-Functions/Base64String/Base64String.Tests.ps1 index 87ec9f4..ca1b655 100644 --- a/Shared-Functions/Base64String/Base64String.Tests.ps1 +++ b/Shared-Functions/Base64String/Base64String.Tests.ps1 @@ -101,6 +101,9 @@ Describe 'Base64String encoding compatibility' { @{ InputText = 'AAAAA' } @{ InputText = 'Zg=' } @{ InputText = 'Zm8==' } + @{ InputText = 'Zg======' } + @{ InputText = 'Zm9v====' } + @{ InputText = '====' } @{ InputText = 'Zg===' } @{ InputText = '=Zg=' } @{ InputText = 'Z=g=' } diff --git a/Shared-Functions/Base64String/Base64String.ps1 b/Shared-Functions/Base64String/Base64String.ps1 index b58688c..6cb7f16 100644 --- a/Shared-Functions/Base64String/Base64String.ps1 +++ b/Shared-Functions/Base64String/Base64String.ps1 @@ -74,6 +74,12 @@ Function ConvertFrom-Base64String { 3 { $normalized += '=' } } } + # .NET Framework accepts some over-padded input (for example Zm8==) + # that modern .NET rejects. Validate padding shape before either runtime. + if ($normalized.Contains('=') -and + ($normalized.Length % 4 -ne 0 -or $normalized -cnotmatch '^[A-Za-z0-9+/]+={1,2}$')) { + throw (New-Object System.FormatException -ArgumentList 'Invalid Base64 length or padding.') + } try { $bytes = [System.Convert]::FromBase64String($normalized) } diff --git a/Shared-Functions/Base64String/Base64String.psd1 b/Shared-Functions/Base64String/Base64String.psd1 index e732a9a..89f8885 100644 --- a/Shared-Functions/Base64String/Base64String.psd1 +++ b/Shared-Functions/Base64String/Base64String.psd1 @@ -55,7 +55,7 @@ # ReleaseNotes of this module ReleaseNotes = ' * Add explicit text encoding options while preserving Unicode defaults. - * Correct standard and URL-safe Base64 padding validation. + * Correct Base64 padding validation on .NET Framework and modern .NET. * Support empty strings and per-item pipeline conversion. * Include encoding compatibility regressions for issue #22. ' @@ -71,5 +71,3 @@ # DefaultCommandPrefix = '' } - - diff --git a/Shared-Functions/Base64String/LICENSE b/Shared-Functions/Base64String/LICENSE new file mode 100644 index 0000000..5f75680 --- /dev/null +++ b/Shared-Functions/Base64String/LICENSE @@ -0,0 +1,13 @@ + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + Version 2, December 2004 + + Copyright (C) 2004 Sam Hocevar + + Everyone is permitted to copy and distribute verbatim or modified + copies of this license document, and changing it is allowed as long + as the name is changed. + + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. You just DO WHAT THE FUCK YOU WANT TO. diff --git a/Shared-Functions/Base64String/README.md b/Shared-Functions/Base64String/README.md index 4d85162..4e26d0e 100644 --- a/Shared-Functions/Base64String/README.md +++ b/Shared-Functions/Base64String/README.md @@ -102,10 +102,12 @@ Import-Module Base64String * Add explicit UTF8, BigEndianUnicode, UTF32 and ASCII encoding options while preserving the default UTF-16 little-endian behavior. -* Correct standard and URL-safe Base64 padding validation; reject malformed input. +* Correct standard and URL-safe Base64 padding validation consistently on + .NET Framework and modern .NET; reject malformed input. * Support empty strings and per-item pipeline conversion, preserving existing aliases. -* Include 31 regression cases for encoding interoperability and issue #22. +* Include 34 regression cases for encoding interoperability and issue #22. * Rebuild the reviewed release package reproducibly from matching source files. +* Include the explicitly selected module-local WTFPL license. ### [v1.2.0] Oct 8, 2019 diff --git a/Shared-Functions/Base64String/out/Base64String.ps1 b/Shared-Functions/Base64String/out/Base64String.ps1 index b58688c..6cb7f16 100644 --- a/Shared-Functions/Base64String/out/Base64String.ps1 +++ b/Shared-Functions/Base64String/out/Base64String.ps1 @@ -74,6 +74,12 @@ Function ConvertFrom-Base64String { 3 { $normalized += '=' } } } + # .NET Framework accepts some over-padded input (for example Zm8==) + # that modern .NET rejects. Validate padding shape before either runtime. + if ($normalized.Contains('=') -and + ($normalized.Length % 4 -ne 0 -or $normalized -cnotmatch '^[A-Za-z0-9+/]+={1,2}$')) { + throw (New-Object System.FormatException -ArgumentList 'Invalid Base64 length or padding.') + } try { $bytes = [System.Convert]::FromBase64String($normalized) } diff --git a/Shared-Functions/Base64String/out/Base64String.psd1 b/Shared-Functions/Base64String/out/Base64String.psd1 index e732a9a..89f8885 100644 --- a/Shared-Functions/Base64String/out/Base64String.psd1 +++ b/Shared-Functions/Base64String/out/Base64String.psd1 @@ -55,7 +55,7 @@ # ReleaseNotes of this module ReleaseNotes = ' * Add explicit text encoding options while preserving Unicode defaults. - * Correct standard and URL-safe Base64 padding validation. + * Correct Base64 padding validation on .NET Framework and modern .NET. * Support empty strings and per-item pipeline conversion. * Include encoding compatibility regressions for issue #22. ' @@ -71,5 +71,3 @@ # DefaultCommandPrefix = '' } - - diff --git a/Shared-Functions/Base64String/out/README.md b/Shared-Functions/Base64String/out/README.md index 4d85162..4e26d0e 100644 --- a/Shared-Functions/Base64String/out/README.md +++ b/Shared-Functions/Base64String/out/README.md @@ -102,10 +102,12 @@ Import-Module Base64String * Add explicit UTF8, BigEndianUnicode, UTF32 and ASCII encoding options while preserving the default UTF-16 little-endian behavior. -* Correct standard and URL-safe Base64 padding validation; reject malformed input. +* Correct standard and URL-safe Base64 padding validation consistently on + .NET Framework and modern .NET; reject malformed input. * Support empty strings and per-item pipeline conversion, preserving existing aliases. -* Include 31 regression cases for encoding interoperability and issue #22. +* Include 34 regression cases for encoding interoperability and issue #22. * Rebuild the reviewed release package reproducibly from matching source files. +* Include the explicitly selected module-local WTFPL license. ### [v1.2.0] Oct 8, 2019