feat: use SecureString for tokens

This is a breaking change, see the readme how tokens should be specified going forward.

Author: felixfbecker

README.md

@@ -41,9 +41,32 @@ Missing something? Please file an issue!
 
 ## Configuration
 
-You can configure a default endpoint and token to be used by modifying `$PSDefaultParameterValues` in your `$PROFILE`:
+You can use a private instance by passing an instance URL with the `-Endpoint` parameter and an API token with the `-Token` parameter to any command.
+The token must be a `SecureString` for security.
+To configure a default endpoint and token to use, modify `$PSDefaultParameterValues` in your `$PROFILE`:
+
+### On Windows
+
+```powershell
+$PSDefaultParameterValues['*Sourcegraph*:Endpoint'] = 'https://sourcegraph.example.com'
+$PSDefaultParameterValues['*Sourcegraph*:Token'] = 'YOUR_ENCRYPTED_TOKEN' | ConvertTo-SecureString
+```
+
+To get the value for `YOUR_ENCRYPTED_TOKEN`, run `Read-Host -AsSecureString | ConvertFrom-SecureString` once
+and paste in your token.
+
+### On macOS/Linux
+
+macOS and Linux do not have access to the Windows Data Protection API, so they cannot use
+`ConvertFrom-SecureString` to generate an encrypted plaintext version of the token without a custom encryption
+key.
+
+If you are not concerned about storing the token in plain text in the `profile.ps1`, you can set it like this:
 
 ```powershell
-$PSDefaultParameterValues['*Sourcegraph*:Token'] = '5c01fd47a2b2187c2947f8a2eb76b358f3ed0e26'
 $PSDefaultParameterValues['*Sourcegraph*:Endpoint'] = 'https://sourcegraph.example.com'
+$PSDefaultParameterValues['*Sourcegraph*:Token'] = 'YOUR_PLAINTEXT_TOKEN' | ConvertTo-SecureString -AsPlainText -Force
 ```
+
+Alternatively, you could store the token in a password manager or the Keychain, then retrieve it in your
+profile and set it the same way.

src/api.psm1

@@ -34,16 +34,15 @@ function Invoke-SourcegraphApiRequest {
         $Variables = @{},
 
         [Uri] $Endpoint = 'https://sourcegraph.com',
-
-        [string] $Token
+        [SecureString] $Token
     )
 
     $uri = [Uri]::new([Uri]::new($Endpoint), '/.api/graphql')
     $header = @{
         "User-Agent" = "Sourcegraph for PowerShell"
     }
-    if (-not [string]::IsNullOrEmpty($Token)) {
-        $header["Authorization"] = "token $Token"
+    if ($Token) {
+        $header["Authorization"] = "token $($Token | ConvertFrom-SecureString -AsPlainText)"
     }
     $body = @{
         query     = $Query

src/codeintel.psm1

@@ -30,8 +30,6 @@ function Get-SourcegraphHover {
     #>
     [CmdletBinding()]
     param(
-        [Uri] $Endpoint = 'https://sourcegraph.com',
-
         [ValidateNotNullOrEmpty()]
         [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
         [string] $RepositoryName,
@@ -52,8 +50,8 @@ function Get-SourcegraphHover {
         [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
         [int[]] $CharacterNumber, # Supports multiple character numbers to support piping a LineMatch
 
-        [ValidateNotNullOrEmpty()]
-        [string] $Token
+        [Uri] $Endpoint = 'https://sourcegraph.com',
+        [SecureString] $Token
     )
 
     process {
@@ -143,7 +141,7 @@ function Get-SourcegraphDefinition {
         [int[]] $CharacterNumber, # Supports multiple character numbers to support piping a LineMatch
 
         [ValidateNotNullOrEmpty()]
-        [string] $Token
+        [SecureString] $Token
     )
 
     process {
@@ -238,7 +236,7 @@ function Get-SourcegraphReference {
         [int] $PageSize = 50,
 
         [ValidateNotNullOrEmpty()]
-        [string] $Token
+        [SecureString] $Token
     )
 
     process {

src/repos.psm1

@@ -39,8 +39,7 @@ function Get-SourcegraphRepository {
         [switch] $Descending,
 
         [Uri] $Endpoint = 'https://sourcegraph.com',
-        [ValidateNotNullOrEmpty()]
-        [string] $Token
+        [SecureString] $Token
     )
     process {
         if ($Id -or $CloneUrl) {

src/search.psm1

@@ -37,7 +37,7 @@ function Search-Sourcegraph {
         [switch] $Structural,
 
         [Uri] $Endpoint = 'https://sourcegraph.com',
-        [string] $Token
+        [SecureString] $Token
     )
 
     process {
@@ -119,7 +119,7 @@ function Get-SourcegraphSearchSuggestions {
         [switch] $Structural,
 
         [Uri] $Endpoint = 'https://sourcegraph.com',
-        [string] $Token
+        [SecureString] $Token
     )
 
     process {

src/users.psm1

@@ -17,8 +17,6 @@ function New-SourcegraphUser {
     #>
     [CmdletBinding(SupportsShouldProcess)]
     param(
-        [Uri] $Endpoint = 'https://sourcegraph.com',
-
         [ValidateNotNullOrEmpty()]
         [Parameter(Mandatory)]
         [string] $Username,
@@ -27,8 +25,8 @@ function New-SourcegraphUser {
         [Parameter(Mandatory)]
         [string] $Email,
 
-        [ValidateNotNullOrEmpty()]
-        [string] $Token
+        [Uri] $Endpoint = 'https://sourcegraph.com',
+        [SecureString] $Token
     )
 
     if ($PSCmdlet.ShouldProcess("Creating user $Username <$Email>", "Create user $Username <$Email>?", "Confirm")) {
@@ -62,7 +60,7 @@ function Get-SourcegraphUser {
         [ValidateSet('TODAY', 'THIS_WEEK', 'THIS_MONTH', 'ALL_TIME')]
         [string] $ActivePeriod,
 
-        [string] $Token
+        [SecureString] $Token
     )
 
     if ($Username) {