Merge pull request #4 from webmd-health-services/feature/rename-to-ca…

…rbon.security

Renaming to Carbon.Security.

.gitignore

@@ -1,8 +1,8 @@
 /.output
 /PSModules
 /.vscode
-/Carbon.Permissions/CHANGELOG.md
-/Carbon.Permissions/LICENSE.txt
-/Carbon.Permissions/NOTICE.txt
-/Carbon.Permissions/README.md
-/Carbon.Permissions/Modules/
+/Carbon.Security/CHANGELOG.md
+/Carbon.Security/LICENSE.txt
+/Carbon.Security/NOTICE.txt
+/Carbon.Security/README.md
+/Carbon.Security/Modules/

CHANGELOG.md

@@ -1,12 +1,12 @@
-# Carbon.Permissions Changelog
+# Carbon.Security Changelog
 
 ## 1.0.0
 
 ### Upgrade Instructions
 
 This is not the upgrade path you want, if switching from Carbon. The `Get-CPermission`, `Grant-CPermission`,
-`Revoke-CPermission`, and `Test-CPermission` functions were migrated to the following modules with the following
-function names.
+`Revoke-CPermission`, and `Test-CPermission` functions were migrated to the following provider-specific modules with the
+following function names:
 
 `Carbon.FileSystem`:
 
@@ -31,52 +31,7 @@ function names.
 * `Revoke-CPrivateKeyPermission`
 * `Test-CPrivateKeyPath`
 
-You *must* switch to `Carbon.Cryptography` if managing permissions on private keys/key containers. `Carbon.Permissions`
-only manages permissions on files, directories, and registry keys.
-
-Replace usages of the `Grant-CPermission` and `Test-CPermission` functions' `ApplyTo` parameter with new parameter
-values and a new `OnlyApplyToChildren` switch:
-
-| Old Parameters                                     | New Parameters
-| -------------------------------------------------- | --------------
-| -ApplyTo Container                                 | -ApplyTo ContainerOnly
-| -ApplyTo SubContainers                             | -ApplyTo SubcontainersOnly
-| -ApplyTo Leaves                                    | -ApplyTo LeavesOnly
-| -ApplyTo ChildContainers                           | -ApplyTo SubcontainersOnly -OnlyApplyToChildren
-| -ApplyTo ChildLeaves                               | -ApplyTo LeavesOnly -OnlyApplyToChildren
-| -ApplyTo ContainerAndSubContainers                 | -ApplyTo ContainerAndSubcontainers
-| -ApplyTo ContainerAndLeaves                        | -ApplyTo ContainerAndLeaves
-| -ApplyTo SubContainerAndLeaves                     | -ApplyTo SubcontainersAndLeavesOnly
-| -ApplyTo ContainerAndChildContainers               | -ApplyTo ContainerAndSubcontainers -OnlyApplyToChildren
-| -ApplyTo ContainerAndChildLeaves                   | -ApplyTo ContainerAndLeaves -OnlyApplyToChildren
-| -ApplyTo ContainerAndChildContainersAndChildLeaves | -ApplyTo ContainerSubcontainersAndLeaves -OnlyApplyToChildren
-| -ApplyTo ContainerAndSubContainersAndLeaves        | -ApplyTo ContainerSubcontainersAndLeaves
-| -ApplyTo ChildContainersAndChildLeaves             | -ApplyTo SubcontainersAndLeavesOnly -OnlyApplyToChildren
-
-Replace usages of `Get-Permissions` with `Get-CPermission`.
-
-Replace usages of `Grant-Permissions` with `Grant-CPermission`.
-
-Rename usages of the `Get-CPermission` and `Test-CPermission` functions' `Exact` switch to `Strict`.
-
 ### Added
 
-* Function `Get-CPermission`, migrated from Carbon.
-* Function `Grant-CPermission`, migrated from Carbon.
-* Function `Revoke-CPermission`, migrated from Carbon.
-* Function `Test-CPermission`, migrated from Carbon.
 * Function `Get-CAcl` to get the access control (i.e. security descriptor) for a registry key, file, or directory.
-Supports getting only specific sections/parts of the security descriptor, too.
-
-### Changed
-
-* Switch `Exact` renamed to `Strict` on the `Get-CPermission` and `Test-CPermission` functions.
-
-### Removed
-
-* Alias `Get-Permissions`. Use `Get-CPermission` instead.
-* Alias `Grant-Permissions`. Use `Grant-CPermission` instead.
-* Private key/key container support from `Get-CPermission`, `Grant-CPermission`, `Revoke-CPermission`, and
-`Test-CPermission`. Switch to the `Carbon.Cryptography` module's `Get-CPrivateKey`, `Get-CPrivateKeyPermission`,
-`Grant-CPrivateKeyPermission`, `Resolve-CPrivateKeyPath`, `Revoke-CPrivateKeyPermission`, and `Test-CPrivateKeyPath`
-instead.
+Supports getting only specific sections/parts of the security descriptor, too. Works across PowerShell editions.

Carbon.Permissions/Carbon.Permissions.psd1 → Carbon.Security/Carbon.Security.psd1

@@ -15,7 +15,7 @@
 @{
 
     # Script module or binary module file associated with this manifest.
-    RootModule = 'Carbon.Permissions.psm1'
+    RootModule = 'Carbon.Security.psm1'
 
     # Version number of this module.
     ModuleVersion = '1.0.0'
@@ -36,7 +36,7 @@
     Copyright = '(c) WebMD Health Services.'
 
     # Description of the functionality provided by this module
-    Description = 'Managing file system, registry, and private key permissions.'
+    Description = 'Manages security.'
 
     # Minimum version of the Windows PowerShell engine required by this module
     PowerShellVersion = '5.1'
@@ -101,31 +101,28 @@
     # List of all files packaged with this module
     # FileList = @()
 
-    # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
+    # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData
+    # hashtable with additional module metadata used by PowerShell.
     PrivateData = @{
 
         PSData = @{
 
-            # Tags applied to this module. These help with module discovery in online galleries.
-            Tags = @(
-                'Desktop', 'Core', 'permission', 'accesscontrol', 'access', 'control', 'securitydescriptor',
-                'security', 'descriptor', 'acl', 'file', 'directory', 'registry', 'acl', 'icacls', 'certificate',
-                'crypto', 'key', 'cryptokey', 'cryptokeysecrurity', 'private', 'cng', 'privatekey', 'grant', 'revoke'
-            )
+            # Tags applied to this module. We don't want people to find this module.
+            Tags = @( 'Desktop', 'Core', 'acl' )
 
             # A URL to the license for this module.
             LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'
 
             # A URL to the main website for this project.
-            ProjectUri = 'https://github.com/webmd-health-services/Carbon.Permissions'
+            ProjectUri = 'https://github.com/webmd-health-services/Carbon.Security'
 
             # A URL to an icon representing this module.
             # IconUri = ''
 
             Prerelease = ''
 
             # ReleaseNotes of this module
-            ReleaseNotes = 'https://github.com/webmd-health-services/Carbon.Permissions/blob/main/CHANGELOG.md'
+            ReleaseNotes = 'https://github.com/webmd-health-services/Carbon.Security/blob/main/CHANGELOG.md'
         } # End of PSData hashtable
 
     } # End of PrivateData hashtable

Carbon.Security/en-US/about_Carbon.Permissions.help.txt

@@ -0,0 +1,30 @@
+TOPIC
+    about_Carbon.Security
+
+SHORT DESCRIPTION
+    The "Carbon.Security" module has a `Get-CAcl` function that gets an item's ACL that works across PowerShell
+    editions.
+
+LONG DESCRIPTION
+    SYSTEM REQUIREMENTS
+
+    * Windows PowerShell 5.1 and .NET 4.6.1+
+    * PowerShell 7+
+
+
+    INSTALLING
+
+    To install globally:
+
+        Install-Module -Name 'Carbon.Security'
+        Import-Module -Name 'Carbon.Security'
+
+    To install privately:
+
+        Save-Module -Name 'Carbon.Security' -Path '.'
+        Import-Module -Name '.\Carbon.Security'
+
+
+    COMMANDS
+
+    * `Get-CAcl`: Gets the access control (i.e. security descriptor) for a file, directory, or registry key.

NOTICE.txt

@@ -1,4 +1,4 @@
-Carbon.Permissions
+Carbon.Security
 
 Copyright 2023 WebMD Health Services
 

README.md

@@ -1,11 +1,10 @@
 <!-- markdownlint-disable MD012 no-multiple-blanks -->
-# Carbon.Permissions PowerShell Module
+# Carbon.Security PowerShell Module
 
 
 ## Overview
 
-The "Carbon.Permissions" module manages permissions on files, directories, registry keys, and certificate private
-keys/key containers.
+The "Carbon.Security" module has a function get an ACLs that works across PowerShell editions.
 
 
 ## System Requirements
@@ -19,23 +18,17 @@ keys/key containers.
 To install globally:
 
 ```powershell
-Install-Module -Name 'Carbon.Permissions'
-Import-Module -Name 'Carbon.Permissions'
+Install-Module -Name 'Carbon.Security'
+Import-Module -Name 'Carbon.Security'
 ```
 
 To install privately:
 
 ```powershell
-Save-Module -Name 'Carbon.Permissions' -Path '.'
-Import-Module -Name '.\Carbon.Permissions'
+Save-Module -Name 'Carbon.Security' -Path '.'
+Import-Module -Name '.\Carbon.Security'
 ```
 
 ## Commands
 
 * `Get-CAcl`: Gets the access control (i.e. security descriptor) for a file, directory, or registry key.
-* `Get-CPermission`: Gets the permissions (access control rules) for a file, directory, registry key, or certificate
-  private key/key container.
-* `Grant-CPermission`: Grants permissions on a file, directory, registry key, or certificate private key/key container.
-* `Revoke-CPermission`: Revokes permissions on a file, directory, registry key, or certificate private key/key
-  container.
-* `Test-CPermission`: Tests permissions on a file, directory, registry key, or certificate private key/key container.

Tests/Carbon.Permissions.Tests.ps1 → Tests/Carbon.Security.Tests.ps1

@@ -17,7 +17,7 @@ BeforeAll {
         )
 
         $verbs =
-            Get-Command -Module 'Carbon.Permissions'|
+            Get-Command -Module 'Carbon.Security'|
             Where-Object { $_ -isnot [Management.Automation.AliasInfo] } |
             Select-Object -ExpandProperty Verb |
             Select-Object -Unique
@@ -64,10 +64,10 @@ BeforeAll {
     }
 }
 
-Describe 'Carbon.Permissions' {
+Describe 'Carbon.Security' {
     It 'should have about help topic' {
         GivenModuleImported
-        ThenHelpTopic 'about_Carbon.Permissions' -Exists
+        ThenHelpTopic 'about_Carbon.Security' -Exists
     }
 
     It 'should only use approved verbs' {
@@ -77,7 +77,7 @@ Describe 'Carbon.Permissions' {
 
     It 'should have a help topic for each command' {
         GivenModuleImported
-        foreach( $cmd in (Get-Command -Module 'Carbon.Permissions' -CommandType Function,Cmdlet,Filter))
+        foreach( $cmd in (Get-Command -Module 'Carbon.Security' -CommandType Function,Cmdlet,Filter))
         {
             ThenHelpTopic $cmd.Name -Exists -HasSynopsis -HasDescription -HasExamples
         }

Tests/Grant-CPermission.Tests.ps1

@@ -9,7 +9,7 @@ BeforeAll {
 
     & (Join-Path -Path $PSScriptRoot -ChildPath 'Initialize-Test.ps1' -Resolve)
 
-    $psModulesSharedPath = Join-Path -Path $PSScriptRoot -ChildPath '..\Carbon.Permissions\Modules' -Resolve
+    $psModulesSharedPath = Join-Path -Path $PSScriptRoot -ChildPath '..\Carbon.Security\Modules' -Resolve
     Import-Module -Name (Join-Path -Path $psModulesSharedPath -ChildPath 'Carbon.Core' -Resolve) `
                   -Function ('Get-CPathProvider') `
                   -Global `
@@ -394,11 +394,11 @@ Describe 'Grant-CPermission' {
         Invoke-GrantPermissions -Identity $script:user -Permission FullControl -Path $containerPath
         ThenPermission -On $containerPath -For $script:user -Is ([FileSystemRights]::FullControl)
 
-        Mock -CommandName 'Set-Acl' -Verifiable -ModuleName 'Carbon.Permissions'
+        Mock -CommandName 'Set-Acl' -Verifiable -ModuleName 'Carbon.Security'
 
         Invoke-GrantPermissions -Identity $script:user -Permission FullControl -Path $containerPath
         ThenPermission -On $containerPath -For $script:user -Is ([FileSystemRights]::FullControl)
-        Should -Invoke 'Set-Acl' -Times 0 -ModuleName 'Carbon.Permissions'
+        Should -Invoke 'Set-Acl' -Times 0 -ModuleName 'Carbon.Security'
     }
 
     It 'when forcing a permission change and the user already has the permissions' {
@@ -415,15 +415,15 @@ Describe 'Grant-CPermission' {
                        -HasInheritanceFlags [InheritanceFlags]::ObjectInherit `
                        -HasPropagationFlags [PropagationFlags]::NoPropagateInherit
 
-        Mock -CommandName 'Set-Acl' -Verifiable -ModuleName 'Carbon.Permissions'
+        Mock -CommandName 'Set-Acl' -Verifiable -ModuleName 'Carbon.Security'
 
         Grant-CPermission -Identity $script:user `
                           -Permission FullControl `
                           -Path $containerPath `
                           -ApplyTo ContainerAndLeaves `
                           -Force
 
-        Should -Invoke 'Set-Acl' -Times 1 -Exactly -ModuleName 'Carbon.Permissions'
+        Should -Invoke 'Set-Acl' -Times 1 -Exactly -ModuleName 'Carbon.Security'
     }
 
     It 'when an item is hidden' {

Tests/Initialize-Test.ps1

@@ -31,8 +31,8 @@ try
     Remove-Module -Name 'Carbon' -Force -ErrorAction Ignore
 
     $modules = [ordered]@{
-        'Carbon.Permissions' = '..\Carbon.Permissions';
-        'Carbon.PermissionsTestHelper' = 'Carbon.PermissionsTestHelper';
+        'Carbon.Security' = '..\Carbon.Security';
+        'Carbon.SecurityTestHelper' = 'Carbon.SecurityTestHelper';
     }
     foreach( $moduleName in $modules.Keys )
     {

Tests/Revoke-CPermission.Tests.ps1

@@ -27,11 +27,11 @@ Describe 'Revoke-CPermission' {
     It 'when user has multiple access control entries on an item' {
         Grant-CPermission -Path $script:testDirPath -Identity $script:username -Permission 'Read'
         $perm = Get-CPermission -Path $script:testDirPath -Identity $script:username
-        Mock -CommandName 'Get-CPermission' -ModuleName 'Carbon.Permissions' -MockWith { $perm ; $perm }.GetNewClosure()
+        Mock -CommandName 'Get-CPermission' -ModuleName 'Carbon.Security' -MockWith { $perm ; $perm }.GetNewClosure()
         $Global:Error.Clear()
         Revoke-CPermission -Path $script:testDirPath -Identity $script:username
         $Global:Error | Should -BeNullOrEmpty
-        Carbon.Permissions\Get-CPermission -Path $script:testDirPath -Identity $script:username | Should -BeNullOrEmpty
+        Carbon.Security\Get-CPermission -Path $script:testDirPath -Identity $script:username | Should -BeNullOrEmpty
     }
 
     It 'should revoke permission' {

init.ps1

@@ -1,10 +1,10 @@
 <#
 .SYNOPSIS
-Gets your computer ready to develop the Carbon.Permissions module.
+Gets your computer ready to develop the Carbon.Security module.
 
 .DESCRIPTION
 The init.ps1 script makes the configuraion changes necessary to get your computer ready to develop for the
-Carbon.Permissions module. It:
+Carbon.Security module. It:
 
 
 .EXAMPLE