Merge pull request #155 from petrsnd/feature/petrsnd/filter-a2a-retrievable

Add support for filtering a2a retrievable accounts

Author: petrsnd

AGENTS.md

@@ -224,6 +224,7 @@ pwsh -File Invoke-SafeguardTests.ps1 -ListSuites
 
 | Suite | Tests | What it covers |
 |---|---|---|
+| A2ARetrievableAccounts | 6 | A2A retrievable account listing and SCIM filter support (requires test certs) |
 | AccessTokenAuth | 5 | Pre-obtained access token authentication |
 | AnonymousAccess | 3 | Unauthenticated Notification service access |
 | ApiInvocation | 12 | GET/POST/PUT/DELETE, filters, ordering, full responses |
@@ -278,6 +279,12 @@ echo '<password>' | java -jar $jar -a <appliance> -u admin -p -x --download-stre
 
 # Streaming upload
 echo '<password>' | java -jar $jar -a <appliance> -u admin -p -x --upload-stream Appliance/Backups/Upload --upload-file backup.sgb
+
+# A2A — list all retrievable accounts (certificate auth)
+echo '<cert-password>' | java -jar $jar -a <appliance> -c <pfx-file> -p -x --retrievable-accounts
+
+# A2A — list retrievable accounts with SCIM filter
+echo '<cert-password>' | java -jar $jar -a <appliance> -c <pfx-file> -p -x --retrievable-accounts --filter "AccountName eq 'myaccount'"
 ```
 
 ### Module-to-suite mapping
@@ -297,7 +304,7 @@ When you change a specific SDK module, run the relevant suite(s) rather than the
 | `SafeguardForPrivilegedSessions.java` | SpsIntegration (requires SPS appliance) |
 | `*Streaming*` classes | Streaming |
 | `event/` classes | (no automated suite yet — test manually) |
-| `SafeguardA2AContext.java` | (no automated suite yet — requires A2A app setup) |
+| `SafeguardA2AContext.java` | A2ARetrievableAccounts (requires test certs) |
 
 ### Fixing test failures
 
@@ -663,6 +670,7 @@ Create `TestFramework/Suites/Suite-YourFeature.ps1` returning a hashtable:
 | Function | Purpose |
 |---|---|
 | `Invoke-SgJSafeguardApi` | Call Safeguard API via the test tool. Supports `-Service`, `-Method`, `-RelativeUrl`, `-Body`, `-Full`, `-Anonymous`, `-Pkce`, `-Username`, `-Password`, `-AccessToken` |
+| `Invoke-SgJSafeguardA2a` | List A2A retrievable accounts via certificate auth. Supports `-CertificateFile`, `-CertificatePassword`, `-Filter`, `-ParseJson` |
 | `Invoke-SgJTokenCommand` | Token operations: `GetToken`, `TokenLifetime`, `RefreshToken`, `Logout` |
 | `Test-SgJAssert` | Assert that a script block returns `$true` |
 | `Test-SgJAssertThrows` | Assert that a script block throws an error |

README.md

@@ -50,6 +50,27 @@ specified passwords can be retrieved with a single method call without
 requiring access request workflow approvals. Safeguard A2A is protected by
 API keys and IP restrictions in addition to client certificate authentication.
 
+### A2A Retrievable Accounts
+
+You can list accounts available for A2A credential retrieval, and optionally
+filter them using a SCIM-style filter string (Safeguard v2.8+):
+
+```Java
+ISafeguardA2AContext a2aContext = Safeguard.A2A.getContext("safeguard.sample.corp", "C:\\client.pfx", password, null, true);
+
+// List all retrievable accounts
+List<IA2ARetrievableAccount> accounts = a2aContext.getRetrievableAccounts();
+
+// Filter by account name (server-side SCIM filter)
+List<IA2ARetrievableAccount> filtered = a2aContext.getRetrievableAccounts("AccountName eq 'myServiceAccount'");
+
+// Use the API key from a retrievable account to fetch the password
+char[] apiKey = accounts.get(0).getApiKey();
+char[] password = a2aContext.retrievePassword(apiKey);
+
+a2aContext.dispose();
+```
+
 SafeguardJava includes an SDK for listening to Safeguard's powerful, real-time
 event notification system. Safeguard provides role-based event notifications
 via SignalR to subscribed clients. If a Safeguard user is an Asset Administrator

TestFramework/SafeguardTestFramework.psm1

@@ -516,6 +516,88 @@ function Invoke-SgJSafeguardSessions {
     return Invoke-SgJSafeguardTool -Arguments $toolArgs -StdinLine $Context.SpsPassword -ParseJson $ParseJson
 }
 
+function Invoke-SgJSafeguardA2a {
+    <#
+    .SYNOPSIS
+        Convenience wrapper for A2A operations via SafeguardJavaTool.
+    .DESCRIPTION
+        Creates an A2A context using a client certificate and performs one of:
+        listing retrievable accounts (with optional SCIM filter), retrieving
+        a password, or setting a password.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [PSCustomObject]$Context,
+
+        [Parameter(Mandatory)]
+        [string]$CertificateFile,
+
+        [Parameter()]
+        [string]$CertificatePassword,
+
+        [Parameter()]
+        [string]$Filter,
+
+        [Parameter()]
+        [string]$ApiKey,
+
+        [Parameter()]
+        [switch]$RetrievePassword,
+
+        [Parameter()]
+        [switch]$SetPassword,
+
+        [Parameter()]
+        [string]$NewPassword,
+
+        [Parameter()]
+        [bool]$ParseJson = $true
+    )
+
+    if (-not $Context) { $Context = Get-SgJTestContext }
+
+    $stdinLines = @()
+
+    if ($RetrievePassword) {
+        if (-not $ApiKey) { throw "Invoke-SgJSafeguardA2a: -ApiKey is required for -RetrievePassword" }
+        $toolArgs = "-a $($Context.Appliance) -x --retrieve-password --api-key `"$ApiKey`" -c `"$CertificateFile`""
+        if ($CertificatePassword) {
+            $toolArgs += " -p"
+            $stdinLines += $CertificatePassword
+        }
+        Write-Verbose "Invoke-SgJSafeguardA2a: retrieve-password"
+        $stdinLine = if ($stdinLines.Count -gt 0) { $stdinLines -join "`n" } else { $null }
+        return Invoke-SgJSafeguardTool -Arguments $toolArgs -StdinLine $stdinLine -ParseJson $false
+    }
+    elseif ($SetPassword) {
+        if (-not $ApiKey) { throw "Invoke-SgJSafeguardA2a: -ApiKey is required for -SetPassword" }
+        if (-not $NewPassword) { throw "Invoke-SgJSafeguardA2a: -NewPassword is required for -SetPassword" }
+        $toolArgs = "-a $($Context.Appliance) -x --set-password --api-key `"$ApiKey`" -c `"$CertificateFile`""
+        if ($CertificatePassword) {
+            $toolArgs += " -p"
+            $stdinLines += $CertificatePassword
+        }
+        $stdinLines += $NewPassword
+        Write-Verbose "Invoke-SgJSafeguardA2a: set-password"
+        $stdinLine = $stdinLines -join "`n"
+        return Invoke-SgJSafeguardTool -Arguments $toolArgs -StdinLine $stdinLine -ParseJson $false
+    }
+    else {
+        $toolArgs = "-a $($Context.Appliance) -x --retrievable-accounts -c `"$CertificateFile`""
+        if ($CertificatePassword) {
+            $toolArgs += " -p"
+            $stdinLines += $CertificatePassword
+        }
+        if ($Filter) {
+            $toolArgs += " --filter `"$Filter`""
+        }
+        Write-Verbose "Invoke-SgJSafeguardA2a: retrievable-accounts"
+        $stdinLine = if ($stdinLines.Count -gt 0) { $stdinLines -join "`n" } else { $null }
+        return Invoke-SgJSafeguardTool -Arguments $toolArgs -StdinLine $stdinLine -ParseJson $ParseJson
+    }
+}
+
 function Test-SgJSpsConfigured {
     <#
     .SYNOPSIS