[Feature] Auth - Login in with PowerShell (#18)

Adds a component for Auth:
- Supports login with PAT using the `-AccessToken` parameter. - Fixes #8
- Supports login with PAT from environment vars `GH_TOKEN` and
`GITHUB_TOKEN` - Fixes #9
- Supports login using Device Flow authorization:
  - with a GitHub App, the preferred way (default) Fixes #10 
- with a OAuth app, the less preferred way. Use parameter `-Mode
OAuthApp` - Fixes #11
- refresh the access token using a refresh token by providing the
`-Refresh` param. - Fixes #17

Author: MariusStorhaug

.github/workflows/Test.GitHub.yml

@@ -0,0 +1,81 @@
+name: Test [GitHub]
+
+on:
+  workflow_dispatch:
+
+permissions: write-all
+
+jobs:
+  TestGitHub:
+    name: Test GitHub
+    if: always()
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    env:
+      GH_TOKEN: ${{ github.token }} # Used for GitHub CLI authentication
+    steps:
+    - name: Test Authentication using auto PAT
+      if: always()
+      shell: pwsh
+      run: |
+        Write-Output '::group::[Debug info] - Environment variables'
+        $env:GITHUB_REPOSITORY_NAME = $env:GITHUB_REPOSITORY.Split('/')[1]
+        Get-ChildItem Env:
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::[Debug info] - File structure'
+        Write-Verbose "Current directory: $((Get-Location).Path)" -Verbose
+        Write-Verbose "------------------------------------" -Verbose
+        Write-Verbose "Current directory content:" -Verbose
+        Get-ChildItem -Path . -Recurse | Select-Object -ExpandProperty FullName | Sort-Object
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Install-Module -Name GitHub -Verbose -Force'
+        Install-Module -Name GitHub -Verbose -Force
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Get-GitHubConfig'
+        Get-GitHubConfig
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Get-GitHubWorkflow -Repo $env:GITHUB_REPOSITORY_NAME -Owner $env:GITHUB_REPOSITORY_OWNER -Verbose'
+        Get-GitHubWorkflow -Repo $env:GITHUB_REPOSITORY_NAME -Owner $env:GITHUB_REPOSITORY_OWNER -Verbose
+        Write-Output '::endgroup::'
+
+    - name: Test Authentication using Specific PAT
+      if: always()
+      shell: pwsh
+      run: |
+        Write-Output '::group::[Debug info] - Environment variables'
+          $env:GITHUB_REPOSITORY_NAME = $env:GITHUB_REPOSITORY.Split('/')[1]
+          Get-ChildItem Env:
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::[Debug info] - File structure'
+          Write-Verbose "Current directory: $((Get-Location).Path)" -Verbose
+          Write-Verbose "------------------------------------" -Verbose
+          Write-Verbose "Current directory content:" -Verbose
+          Get-ChildItem -Path . -Recurse | Select-Object -ExpandProperty FullName | Sort-Object
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Install-Module -Name GitHub -Verbose -Force'
+          Install-Module -Name GitHub -Verbose -Force
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Get-GitHubConfig'
+          Get-GitHubConfig
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Connect-GitHubAccount -AccessToken $env:GH_TOKEN -Verbose'
+          Connect-GitHubAccount -AccessToken $env:GH_TOKEN -Verbose
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Get-GitHubConfig'
+          Get-GitHubConfig
+        Write-Output '::endgroup::'
+
+        Write-Output '::group::Get-GitHubWorkflow -Repo $env:GITHUB_REPOSITORY_NAME -Owner $env:GITHUB_REPOSITORY_OWNER -Verbose'
+          Get-GitHubWorkflow -Repo $env:GITHUB_REPOSITORY_NAME -Owner $env:GITHUB_REPOSITORY_OWNER -Verbose
+        Write-Output '::endgroup::'

README.md

@@ -26,11 +26,34 @@ To dive into the world of GitHub automation with PowerShell, follow these steps:
 
 1. **Installation**: Download and install the GitHub PowerShell module from the provided link or the PowerShell Gallery.
 
-2. **Authentication**: Authenticate using your GitHub credentials or access tokens to begin executing commands.
+    ```powershell
+    Install-Module -Name GitHub -Force -AllowClobber
+    ```
 
-3. **Command Exploration**: Familiarize yourself with the available cmdlets using the module's comprehensive documentation or inline help.
+1. **Authentication**: Authenticate using your GitHub credentials or access tokens to begin executing commands.
 
-4. **Sample Scripts**: Check out sample scripts and usage patterns to jumpstart your automation tasks on GitHub.
+Logging in using device flow:
+```powershell
+Connect-GitHubAccount
+
+Please visit: https://github.com/login/device
+and enter code: ABCD-1234
+Successfully authenticated!
+```
+
+Logging in using PAT token:
+```powershell
+>_ Connect-GitHubAccount -AccessToken 'ghp_abcdefghklmnopqrstuvwxyz123456789123'
+>_
+```
+
+2. **Command Exploration**: Familiarize yourself with the available cmdlets using the module's comprehensive documentation or inline help.
+
+    ```powershell
+    Get-Command -Module GitHub
+    ```
+
+3. **Sample Scripts**: Check out sample scripts and usage patterns to jumpstart your automation tasks on GitHub.
 
 ## More Information & Resources
 

media/github.png

@@ -0,0 +1,14 @@
+Write-Verbose "Initializing GitHub module..." -Verbose
+
+$script:Config = $script:ConfigTemplate | ConvertTo-Json -Depth 100 | ConvertFrom-Json
+Initialize-SecretVault -Name $script:SecretVault.Name -Type $script:SecretVault.Type
+Restore-GitHubConfig
+
+if (-not [string]::IsNullOrEmpty($env:GH_TOKEN)) {
+    Write-Verbose 'Logging on using GH_TOKEN'
+    Connect-GitHubAccount -AccessToken $env:GH_TOKEN
+}
+if (-not [string]::IsNullOrEmpty($env:GITHUB_TOKEN)) {
+    Write-Verbose 'Logging on using GITHUB_TOKEN'
+    Connect-GitHubAccount -AccessToken $env:GITHUB_TOKEN
+}

src/GitHub/GitHub.ps1

@@ -1,32 +1,53 @@
 [Cmdletbinding()]
 param()
 
-$sciptName = $MyInvocation.MyCommand.Name
+$scriptName = $MyInvocation.MyCommand.Name
+Write-Verbose "[$scriptName] - Importing module"
 
-Write-Verbose "[$sciptName] Importing subcomponents"
-$folders = 'classes', 'private', 'public'
-# Import everything in these folders
+#region - Importing data files
+Write-Verbose "[$scriptName] - [data] - Processing folder"
+$dataFolder = (Join-Path $PSScriptRoot 'data')
+Write-Verbose "[$scriptName] - [data] - [$dataFolder]"
+Get-ChildItem -Path "$dataFolder" -Recurse -Force -Include '*.psd1' | ForEach-Object {
+    Write-Verbose "[$scriptName] - [data] - [$($_.Name)] - Importing data file"
+    New-Variable -Name $_.BaseName -Value (Import-PowerShellDataFile -Path $_.FullName) -Force
+    Write-Verbose "[$scriptName] - [data] - [$($_.Name)] - Done"
+}
+Write-Verbose "[$scriptName] - [data] - Done"
+#endregion - Importing datas
+
+#region - Importing script files
+$folders = 'init', 'classes', 'private', 'public'
 foreach ($folder in $folders) {
-    Write-Verbose "[$sciptName] - Processing folder [$folder]"
+    Write-Verbose "[$scriptName] - [$folder] - Processing folder"
     $folderPath = Join-Path -Path $PSScriptRoot -ChildPath $folder
-    Write-Verbose "[$sciptName] - [$folderPath]"
     if (Test-Path -Path $folderPath) {
-        Write-Verbose "[$sciptName] - [$folderPath] - Getting all files"
-        $files = $null
-        $files = Get-ChildItem -Path $folderPath -Include '*.ps1', '*.psm1' -Recurse
-        # dot source each file
+        $files = Get-ChildItem -Path $folderPath -Include '*.ps1', '*.psm1' -Recurse | Sort-Object -Property FullName
         foreach ($file in $files) {
-            Write-Verbose "[$sciptName] - [$folderPath] - [$($file.Name)] - Importing"
-            Import-Module $file
-            Write-Verbose "[$sciptName] - [$folderPath] - [$($file.Name)] - Done"
+            Write-Verbose "[$scriptName] - [$folder] - [$($file.Name)] - Importing script file"
+            Import-Module $file -Verbose:$false
+            Write-Verbose "[$scriptName] - [$folder] - [$($file.Name)] - Done"
         }
     }
+    Write-Verbose "[$scriptName] - [$folder] - Done"
 }
+#endregion - Importing script files
 
+#region - Importing root script files
+Write-Verbose "[$scriptName] - [PSModuleRoot] - Processing folder"
+Get-ChildItem -Path $PSScriptRoot -Filter '*.ps1' | ForEach-Object {
+    Write-Verbose "[$scriptName] - [PSModuleRoot] - [$($_.Name)] - Importing root script files"
+    Import-Module $_ -Verbose:$false
+    Write-Verbose "[$scriptName] - [PSModuleRoot] - [$($_.Name)] - Done"
+}
+Write-Verbose "[$scriptName] - [Root] - Done"
+#endregion - Importing root script files
+
+#region Export module members
 $foldersToProcess = Get-ChildItem -Path $PSScriptRoot -Directory | Where-Object -Property Name -In $folders
 $moduleFiles = $foldersToProcess | Get-ChildItem -Include '*.ps1' -Recurse -File -Force
 $functions = $moduleFiles.BaseName
-$Param = @{
+$param = @{
     Function = $functions
     Variable = ''
     Cmdlet   = ''
@@ -35,4 +56,7 @@ $Param = @{
 
 Write-Verbose 'Exporting module members'
 
-Export-ModuleMember @Param
+Export-ModuleMember @param
+#endregion Export module members
+
+Write-Verbose "[$scriptName] - Done"

src/GitHub/GitHub.psm1

@@ -0,0 +1,8 @@
+@{
+    GitHubApp = @{
+        ClientID = 'Iv1.f26b61bc99e69405' # $script:Auth.GitHubApp.ClientID
+    }
+    OAuthApp  = @{
+        ClientID = '7204ae9b0580f2cb8288' # $script:Auth.OAuthApp.ClientID
+    }
+}

src/GitHub/classes/Data/Config.ps1

@@ -0,0 +1,7 @@
+@{
+    Name   = 'GitHub'                           # $script:SecretVault.Name
+    Type   = 'Microsoft.PowerShell.SecretStore' # $script:SecretVault.Type
+    Secret = @{
+        Name = 'Config'                           # $script:SecretVault.Secret.Name
+    }
+}

src/GitHub/classes/Data/SecretVault.ps1

@@ -0,0 +1,45 @@
+TOPIC
+    about_Auth
+
+SHORT DESCRIPTION
+    Describes the authentication methods provided in the PowerShell module for interacting with GitHub's REST API.
+
+LONG DESCRIPTION
+    This module provides several functions to manage authentication for GitHub's REST API. There are primarily two ways to authenticate:
+
+    1. GitHub Device Flow: This method prompts the user to visit a specific URL on GitHub where they must enter a user verification code. Once this is done, the module retrieves the necessary access tokens to make authenticated API requests.
+
+    2. Personal Access Token: The user can provide a Personal Access Token (PAT) to authenticate. This PAT allows the module to interact with the API on the user's behalf. The module can automatically use environment variables `GH_TOKEN` or `GITHUB_TOKEN` if they are present.
+
+    The module also provides functionalities to refresh the access token and to disconnect or logout from the GitHub account.
+
+EXAMPLES
+    Example 1:
+        Connect-GitHubAccount
+        Connects to GitHub using the device flow login. You'll be prompted to visit a specific URL on GitHub and enter the provided user verification code.
+
+    Example 2:
+        Connect-GitHubAccount -AccessToken 'ghp_####'
+        Connects to GitHub using a provided personal access token (PAT).
+
+    Example 3:
+        Connect-GitHubAccount -Refresh
+        Refreshes the access token for continued session validity.
+
+    Example 4:
+        Disconnect-GitHubAccount
+        Disconnects from GitHub and removes the current GitHub configuration.
+
+    Example 5 (Automatic login using environment variables):
+        If either the `GH_TOKEN` or `GITHUB_TOKEN` environment variables are set, the module will automatically use them for authentication during module initialization.
+
+KEYWORDS
+    GitHub, Authentication, Device Flow, Personal Access Token, PowerShell, REST API
+
+SEE ALSO
+    For more information on the Device Flow visit:
+    - https://docs.github.com/en/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app
+
+    For information about scopes and other authentication methods on GitHub:
+    - https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
+    - https://docs.github.com/en/rest/overview/other-authentication-methods#authenticating-for-saml-sso