docs(EncryptCredential): add keyfile ACL guidance and scheduled task/service usage

.github/workflows/sqlpipeline.tests.yml

@@ -32,8 +32,8 @@ jobs:
         shell: powershell
         run: |
           Set-PSRepository psgallery -InstallationPolicy trusted
-          Install-Module WriteLog, ImportDependency -Repository PSGallery
-          Install-Module SimplySQL -AllowClobber -Repository PSGallery
+          Install-Module WriteLog, ImportDependency -Repository PSGallery -Scope CurrentUser
+          Install-Module SimplySQL -AllowClobber -Repository PSGallery -Scope CurrentUser
 
       - name: Debug
         run: |
@@ -53,8 +53,8 @@ jobs:
         shell: pwsh
         run: |
           Set-PSRepository psgallery -InstallationPolicy trusted
-          Install-Module WriteLog, ImportDependency -Repository PSGallery
-          Install-Module SimplySQL -AllowClobber -Repository PSGallery
+          Install-Module WriteLog, ImportDependency -Repository PSGallery -Scope CurrentUser
+          Install-Module SimplySQL -AllowClobber -Repository PSGallery -Scope CurrentUser
 
       - name: Run Pester Tests (pwsh on ${{ matrix.os }})
         if: matrix.shell != 'powershell'

EncryptCredential/EncryptCredential/EncryptCredential.psd1

@@ -4,7 +4,7 @@
 RootModule = 'EncryptCredential.psm1'
 
 # Version number of this module.
-ModuleVersion = '0.3.0'
+ModuleVersion = '0.4.0'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()
@@ -135,6 +135,19 @@ PrivateData = @{
 
         # ReleaseNotes of this module
         ReleaseNotes = "
+0.4.0 Added machine-and-user binding to make encrypted strings non-portable.
+      Windows: keyfile is now written as a DPAPI-protected blob (CurrentUser scope)
+        by New-KeyfileRaw. Get-BoundKey calls ProtectedData.Unprotect() to recover
+        the AES key; this only succeeds for the same user on the same machine and is
+        backed by Windows credential infrastructure (LSASS, optionally TPM).
+        Knowing the user SID or machine GUID alone is not sufficient to bypass it.
+      Linux/macOS: key is derived via HMAC-SHA256(key=keyfileBytes,
+        data=machine-id|username|uid), all read from the OS at runtime.
+      Read-Keyfile updated to return DPAPI blobs as-is for Get-BoundKey to handle.
+      Scheduled tasks on Windows must use LogonType=Password to ensure the user
+        profile is loaded (required by DPAPI).
+      BREAKING CHANGE: all previously encrypted strings must be re-encrypted.
+        See 'Migrating to v0.4.0' in the README.
 0.3.0 Reworked the module with Claude AI to be more secure and robust, now using another way to create
       a keyfile for salting. The old encryption method is still supported, so all
       previously encrypted strings will stay valid UNTIL you call New-Keyfile. After that,

EncryptCredential/EncryptCredential/Private/Get-BoundKey.ps1

@@ -0,0 +1,86 @@
+Function Get-BoundKey {
+<#
+    Derives or recovers a machine-and-user-bound 32-byte AES key from raw keyfile bytes.
+
+    SECURITY MODEL
+    --------------
+    Windows
+      New-KeyfileRaw writes the keyfile as a DPAPI-protected blob (CurrentUser scope).
+      Get-BoundKey calls ProtectedData.Unprotect() to recover the original random bytes.
+      Unprotect only succeeds for the same user on the same machine; it is backed by
+      Windows credential infrastructure (LSASS, optionally TPM-backed master key).
+      Unlike the previous HMAC approach, knowing the user SID or machine GUID alone
+      is NOT sufficient — the user's actual login credentials are part of the key
+      material managed by Windows.
+
+    Linux / macOS
+      The keyfile holds raw random bytes (no DPAPI available).
+      An HMAC-SHA256 is computed over those bytes using machine identity
+      (/etc/machine-id) and the current numeric UID as the HMAC key.
+      This raises the bar against cross-machine / cross-user keyfile theft but is
+      a software-only binding — the binding values are not themselves secret.
+
+    In both cases the binding is determined by the operating system at runtime.
+    There is no parameter a caller can supply to override or forge the identity.
+#>
+
+    [OutputType([byte[]])]
+    param(
+        [Parameter(Mandatory=$true)][byte[]]$RawKey
+    )
+
+    if ($PSVersionTable.PSEdition -eq 'Desktop' -or $IsWindows) {
+
+        # Windows: keyfile is a DPAPI blob written by New-KeyfileRaw.
+        # Unprotect recovers the original AES key bytes.
+        # This only succeeds for the same user on the same machine.
+        Add-Type -AssemblyName System.Security
+        try {
+            return [byte[]][System.Security.Cryptography.ProtectedData]::Unprotect(
+                $RawKey,
+                $null,
+                [System.Security.Cryptography.DataProtectionScope]::CurrentUser
+            )
+        } catch [System.Security.Cryptography.CryptographicException] {
+            throw (
+                "Keyfile cannot be decrypted by DPAPI. Possible causes: " +
+                "(1) the keyfile was created on a different machine or by a different user account; " +
+                "(2) it is in the legacy raw-bytes format from v0.3.0 or earlier — " +
+                "see 'Migrating to v0.4.0' in the README."
+            )
+        }
+
+    } else {
+
+        # Linux / macOS: HMAC-SHA256 binding.
+        # machine-id + username + numeric UID are read from the OS at runtime;
+        # they cannot be overridden by the calling script.
+        $machineId = $null
+        foreach ($candidate in @('/etc/machine-id', '/var/lib/dbus/machine-id')) {
+            if (Test-Path -Path $candidate) {
+                $machineId = ([System.IO.File]::ReadAllText($candidate)).Trim()
+                break
+            }
+        }
+        if ([string]::IsNullOrEmpty($machineId)) {
+            throw (
+                "Cannot determine machine identity: neither /etc/machine-id nor " +
+                "/var/lib/dbus/machine-id was found. Ensure one of these files exists."
+            )
+        }
+
+        $userName = [System.Environment]::UserName
+        $uid      = (& id -u 2>$null)
+        $binding  = "${machineId}|${userName}|${uid}"
+
+        $bindingBytes = [System.Text.Encoding]::UTF8.GetBytes($binding)
+        $hmac = [System.Security.Cryptography.HMACSHA256]::new($RawKey)
+        try {
+            return [byte[]]$hmac.ComputeHash($bindingBytes)   # always 32 bytes
+        } finally {
+            $hmac.Dispose()
+        }
+
+    }
+
+}

EncryptCredential/EncryptCredential/Private/New-KeyfileRaw.ps1

@@ -42,11 +42,22 @@ Function New-KeyfileRaw {
             $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
             $rng.GetBytes($Key)
             $rng.Dispose()
-            [System.IO.File]::WriteAllBytes($Path, $Key)
 
-            # Restrict file access to the current user only
             If ($PSVersionTable.PSEdition -eq 'Desktop' -or $IsWindows) {
-                # Windows: remove inherited ACEs, grant current user full control
+
+                # Windows: DPAPI-protect the key bytes before writing to disk.
+                # The resulting blob can only be decrypted by the same user on the
+                # same machine — it is backed by Windows credential infrastructure
+                # (LSASS, optionally TPM).  The raw AES key never touches disk.
+                Add-Type -AssemblyName System.Security
+                $protected = [System.Security.Cryptography.ProtectedData]::Protect(
+                    $Key,
+                    $null,
+                    [System.Security.Cryptography.DataProtectionScope]::CurrentUser
+                )
+                [System.IO.File]::WriteAllBytes($Path, $protected)
+
+                # ACL: also restrict file access to the current user (defence in depth)
                 $acl = Get-Acl -Path $Path
                 $acl.SetAccessRuleProtection($true, $false)
                 $rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
@@ -56,9 +67,13 @@ Function New-KeyfileRaw {
                 )
                 $acl.SetAccessRule($rule)
                 Set-Acl -Path $Path -AclObject $acl
+
             } else {
-                # Linux/macOS: owner read/write only (600)
+
+                # Linux/macOS: save raw bytes, restrict to owner read/write only (600)
+                [System.IO.File]::WriteAllBytes($Path, $Key)
                 & chmod 600 $Path
+
             }
 
         } else {

EncryptCredential/EncryptCredential/Private/Read-Keyfile.ps1

@@ -1,18 +1,22 @@
 Function Read-Keyfile {
 <#
-    Returns the AES key bytes from the keyfile.
-    Supports both formats:
-      - New: raw binary (16/24/32 bytes written with WriteAllBytes)
-      - Legacy: UTF8 text with one decimal number per line (written with Set-Content -Encoding UTF8)
+    Returns raw file bytes for Get-BoundKey to interpret.
+
+    Supports three formats:
+      - Windows v0.4.0+: DPAPI-protected blob (variable length, always > 32 bytes)
+      - Binary (Linux / Windows v0.3.0): raw AES key, exactly 16, 24, or 32 bytes
+      - Legacy text (all platforms, very old): UTF8, one decimal byte value per line
 #>
     param(
         [Parameter(Mandatory=$true)][String]$Path
     )
 
     $rawBytes = [System.IO.File]::ReadAllBytes($Path)
 
-    If ($rawBytes.Length -in @(16, 24, 32)) {
-        # Binary keyfile (new format)
+    # Binary file: either a raw AES key (16/24/32 bytes) or a Windows DPAPI blob (> 32 bytes).
+    # Return as-is in both cases; Get-BoundKey handles the interpretation.
+    If ($rawBytes.Length -in @(16, 24, 32) -or
+        (($PSVersionTable.PSEdition -eq 'Desktop' -or $IsWindows) -and $rawBytes.Length -gt 32)) {
         return $rawBytes
     }
 

EncryptCredential/EncryptCredential/Public/Convert-PlaintextToSecure.ps1

@@ -78,8 +78,9 @@ Function Convert-PlaintextToSecure {
 
         $return = ""
 
-        # read key bytes (handles both binary and legacy text format)
-        $salt = Read-Keyfile -Path $Script:keyfile
+        # read key bytes (handles both binary and legacy text format),
+        # then derive a machine-and-user-bound key so the result is not portable
+        $salt = Get-BoundKey -RawKey (Read-Keyfile -Path $Script:keyfile)
 
         # convert
         $stringSecure = ConvertTo-secureString -String $String -asplaintext -force

EncryptCredential/EncryptCredential/Public/Convert-SecureToPlaintext.ps1

@@ -52,8 +52,10 @@ Function Convert-SecureToPlaintext {
 
         $return = ""
 
-        # read key bytes (handles both binary and legacy text format)
-        $salt = Read-Keyfile -Path $Script:keyfile
+        # read key bytes (handles both binary and legacy text format),
+        # then derive a machine-and-user-bound key so decryption only succeeds
+        # on the same machine and under the same OS user account
+        $salt = Get-BoundKey -RawKey (Read-Keyfile -Path $Script:keyfile)
 
         #convert
         Try {