Merge pull request #157 from petrsnd/feature/modular-agent-context

Reduce AGENTS.md and use skills instead

Author: petrsnd

.agents/skills/architecture/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: architecture
+description: >-
+  Use when working on SDK internals, authentication flows, connection
+  classes, event listeners, A2A contexts, SPS integration, or adding
+  new authentication methods. Covers the rSTS token exchange, strategy
+  pattern, and SignalR event system.
+---
+
+# Architecture Deep Dive
+
+## Entry point (`Safeguard.java`)
+
+The static `Safeguard` class is the SDK's public entry point. All SDK usage starts through
+static factory methods:
+
+- **`Safeguard.connect(...)`** — Creates `ISafeguardConnection` instances. Multiple
+  overloads support password, certificate (keystore/file/thumbprint/byte array), and
+  access token authentication.
+- **`Safeguard.A2A.getContext(...)`** — Creates `ISafeguardA2AContext` for
+  application-to-application credential retrieval. Only supports certificate authentication.
+- **`Safeguard.A2A.Events.getPersistentA2AEventListener(...)`** — Creates auto-reconnecting
+  A2A event listeners.
+- **`Safeguard.Persist(connection)`** — Wraps any connection in a
+  `PersistentSafeguardConnection` that auto-refreshes tokens.
+- **`SafeguardForPrivilegedSessions.Connect(...)`** — Creates
+  `ISafeguardSessionsConnection` for Safeguard for Privileged Sessions (SPS).
+
+## Safeguard API services
+
+The SDK targets five backend services, represented by the `Service` enum:
+
+| Service | Endpoint pattern | Auth required |
+|---|---|---|
+| `Core` | `/service/core/v{version}` | Yes |
+| `Appliance` | `/service/appliance/v{version}` | Yes |
+| `Notification` | `/service/notification/v{version}` | No |
+| `A2A` | `/service/a2a/v{version}` | Certificate |
+| `Management` | `/service/management/v{version}` | Yes |
+
+## Authentication strategy pattern (`authentication/`)
+
+All authenticators implement `IAuthenticationMechanism`. When adding a new authentication
+method:
+1. Implement `IAuthenticationMechanism` in the `authentication/` package
+2. Add `Safeguard.connect()` overload(s) in `Safeguard.java`
+3. Follow the pattern of existing authenticators (extend `AuthenticatorBase`)
+
+### Adding a new authentication method — checklist
+
+1. **Create the authenticator class** in `src/.../authentication/`:
+   - Extend `AuthenticatorBase` (provides rSTS token exchange logic)
+   - Implement `IAuthenticationMechanism` interface methods:
+     - `getId()` — unique identifier string
+     - `getAccessToken()` — obtain token via rSTS
+     - `refreshAccessToken()` — refresh existing token
+     - `getAccessTokenLifetimeRemaining()` — seconds until expiry
+     - `logout()` — revoke token and clean up
+     - `dispose()` — release resources
+   - Follow the `char[]` convention for any credential parameters
+
+2. **Add factory overloads** in `Safeguard.java`:
+   - Add static `connect()` method(s) with appropriate parameters
+   - Include overloads for both `ignoreSsl` boolean and `HostnameVerifier` callback
+   - Include overloads with and without `apiVersion` parameter
+
+3. **Wire up connection creation**:
+   - Instantiate the authenticator, call `connect()` on it
+   - Wrap in `SafeguardConnection` and return as `ISafeguardConnection`
+
+4. **Add tests** — see the testing-guide skill for module-to-suite mapping
+
+## Connection classes
+
+- **`SafeguardConnection`** — Base `ISafeguardConnection` implementation. Makes HTTP calls
+  via `invokeMethod()` / `invokeMethodFull()`.
+- **`PersistentSafeguardConnection`** — Decorator that checks
+  `getAccessTokenLifetimeRemaining() <= 0` before each call and auto-refreshes tokens.
+
+### Token refresh flow in `PersistentSafeguardConnection`
+
+```
+Client calls invokeMethod()
+  → PersistentSafeguardConnection checks getAccessTokenLifetimeRemaining()
+    → If <= 0: calls refreshAccessToken() on the underlying authenticator
+    → Delegates to SafeguardConnection.invokeMethod() with refreshed token
+```
+
+The decorator is transparent — callers interact with `ISafeguardConnection` identically
+regardless of whether persistence is enabled.
+
+## rSTS authentication flow
+
+All authenticators obtain tokens via the embedded Safeguard RSTS (Resource Security Token
+Service) at `https://{host}/RSTS/oauth2/token`.
+
+- **Password authentication** uses the `password` grant type (Resource Owner Grant). **ROG
+  is disabled by default** on modern Safeguard appliances. If ROG is disabled, password
+  auth will fail with a 400 error. It must be explicitly enabled via appliance settings
+  or the test framework's preflight check.
+- **PKCE authentication** (`PasswordAuthenticator` with `usePkce=true`) drives the rSTS
+  login controller at `/RSTS/UserLogin/LoginController` programmatically, exchanging an
+  authorization code for a token. **PKCE is always available** regardless of ROG settings
+  and is the preferred method for interactive/programmatic login.
+- **Certificate authentication** uses the `client_credentials` grant type with a client
+  certificate.
+- **Access token authentication** accepts a pre-obtained token but cannot refresh it.
+
+The test framework handles ROG automatically — it enables ROG before tests run and
+restores the original setting when tests complete. Both ROG and PKCE are valid for tests;
+use whichever is appropriate for the feature being tested.
+
+## Event listeners (`event/`)
+
+- **`SafeguardEventListener`** — Standard SignalR listener. Does NOT survive prolonged outages.
+- **`PersistentSafeguardEventListener`** — Auto-reconnecting persistent listener.
+- **`PersistentSafeguardA2AEventListener`** — Persistent A2A-specific variant.
+- **`EventHandlerRegistry`** — Thread-safe handler dispatch. Each event type gets its own
+  handler thread; handlers for the same event execute sequentially, handlers for different
+  events execute concurrently.
+- Use `getPersistentEventListener()` for production deployments.
+- Event handling code **must use Gson** `JsonElement`/`JsonObject` types (transitive from
+  the SignalR Java client's `GsonHubProtocol`).
+
+### Gson vs Jackson in event handlers (common mistake)
+
+The SignalR Java client uses `GsonHubProtocol`, which means all event payloads arrive as
+Gson `JsonElement` objects. Although the SDK uses Jackson Databind for REST API responses,
+event handler code must use Gson types:
+
+```java
+// CORRECT — Gson types for event payloads
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+
+handler.setHandler(event -> {
+    JsonObject payload = event.getAsJsonObject();
+    String name = payload.get("Name").getAsString();
+});
+
+// WRONG — Jackson types will fail at runtime
+import com.fasterxml.jackson.databind.JsonNode; // Don't use for events
+```
+
+## A2A (`SafeguardA2AContext`)
+
+Certificate-only authentication for automated credential retrieval. Key types:
+`ISafeguardA2AContext`, `A2ARegistration`, `BrokeredAccessRequest`.
+
+A2A contexts use client certificates to authenticate directly — no username/password
+involved. The certificate must be registered as an A2A credential retrieval certificate
+on the appliance.
+
+## SPS integration (`SafeguardForPrivilegedSessions`)
+
+Integration with Safeguard for Privileged Sessions. `ISafeguardSessionsConnection` /
+`SafeguardSessionsConnection`. Connects using basic auth (username/password) over HTTPS.
+
+SPS has its own REST API at `https://<sps-address>/api/`. The `ISafeguardSessionsConnection`
+interface provides `invokeMethod()` / `invokeMethodFull()` similar to the main connection,
+but targets the SPS API instead of the SPP API.
+
+## Certificate handling (`CertificateContext`)
+
+The `CertificateContext` class unifies multiple certificate input formats:
+
+| Input format | Method/Constructor | Notes |
+|---|---|---|
+| JKS keystore | File path + password | Standard Java keystore |
+| PFX/PKCS#12 file | File path + password | Cross-platform format |
+| Byte array | Raw bytes + password | For certificates stored in memory or database |
+| Windows thumbprint | Certificate thumbprint string | Windows certificate store lookup |
+
+When working with certificate authentication, ensure:
+- PFX files include the private key (required for client certificate auth)
+- The certificate chain is complete (or the CA is trusted by the appliance)
+- Passwords are passed as `char[]`, not `String`

.agents/skills/ci-cd-pipeline/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: ci-cd-pipeline
+description: >-
+  Use when modifying Azure Pipelines, build templates, signing
+  configuration, Maven Central publishing, GitHub Packages publishing,
+  or release process. Covers GPG signing, JAR code signing, version
+  strategy, and critical pipeline pitfalls.
+---
+
+# CI/CD Pipeline
+
+The project uses **Azure Pipelines** (`azure-pipelines.yml`) with shared templates in
+`pipeline-templates/`.
+
+## Pipeline architecture
+
+The pipeline has **two jobs**, matching the SafeguardDotNet pattern:
+
+| Job | Runs when | What it does |
+|---|---|---|
+| **PRValidation** | Pull requests only | `mvn package` — compile, lint, SpotBugs |
+| **BuildAndPublish** | Merges to `master`/`release-*` | Build, GPG sign, JAR sign, publish to Maven Central + GitHub Packages, create GitHub Release |
+
+Both jobs share `build-steps.yml` with different parameters. PRValidation uses defaults
+(`package`, no signing); BuildAndPublish passes `deploy`, release profile flags, and
+`signJars: true`.
+
+## Pipeline template files
+
+| File | Scope | Contents |
+|---|---|---|
+| `global-variables.yml` | Pipeline-level | `semanticVersion`, `isPrerelease`, `versionSuffix` |
+| `job-variables.yml` | Job-level | `version` (composed), `targetDir`, `gpgKeyName` |
+| `build-steps.yml` | Steps template | Maven task + optional Docker JAR signing + artifact publishing |
+
+## Version strategy
+
+Version is composed from runtime variables: `$(semanticVersion).$(Build.BuildId)$(versionSuffix)`
+
+- When `isPrerelease: 'true'` → `versionSuffix` is `-SNAPSHOT` → e.g. `8.2.0.355537-SNAPSHOT`
+- When `isPrerelease: 'false'` → `versionSuffix` is empty → e.g. `8.2.0.355537`
+
+The pom.xml uses `<version>${revision}</version>` with CI-friendly properties. The actual
+version is always injected via `-Drevision=$(version)` on the Maven command line.
+
+## Service connections and key vaults
+
+| Service connection | Key vault | Secrets |
+|---|---|---|
+| `SafeguardOpenSource` | `SafeguardBuildSecrets` | `SonatypeUserToken`, `SonatypeRepositoryPassword`, `GpgCodeSigningKey`, `SigningStorePassword`, `GitHubPackagesToken` |
+| `OneIdentity.Infrastructure.SPPCodeSigning` | `SPPCodeSigning` | `SPPCodeSigning-Password`, `SPPCodeSigning-TotpPrivateKey` |
+| `PangaeaBuild-GitHub` | *(none)* | GitHub service connection for Release creation |
+
+## Two signing mechanisms
+
+The pipeline uses **two independent signing mechanisms** that serve different purposes:
+
+### 1. GPG signing (`maven-gpg-plugin`)
+
+Produces `.asc` detached signature files required by Maven Central for release validation.
+Configured in the `release` Maven profile.
+
+- GPG private key: vault secret `GpgCodeSigningKey`, imported via `gpg --batch --import`
+- GPG passphrase: vault secret `SigningStorePassword`
+- `settings/settings.xml` maps the passphrase via a server entry:
+  `<id>${gpgkeyname}</id>` + `<passphrase>${signingkeystorepassword}</passphrase>`
+- Maven command line needs both `-Dsigningkeystorepassword=$(SigningStorePassword)` and
+  `-Dgpgkeyname=$(gpgKeyName)`
+- The plugin uses `--batch --pinentry-mode loopback` for non-interactive passphrase input
+- **CRITICAL:** The GPG plugin is bound to the `verify` lifecycle phase. `mvn package`
+  stops at the `package` phase and **never triggers GPG signing**. Only `mvn deploy`
+  (or `mvn verify` / `mvn install`) reaches the GPG plugin. This means you cannot test
+  GPG signing with `mvn package -P release` — it will succeed silently without signing.
+
+### 2. JAR code signing (SSL.com CodeSigner Docker image)
+
+Embeds certificates in `META-INF/` (CERT.SF, CERT.RSA) inside the JAR for Java runtime
+signature verification.
+
+- Uses Docker image `ghcr.io/sslcom/codesigner:latest` which bundles its own JRE
+- eSigner account: `ssl.oid.safeguardpp@groups.quest.com`
+- Credentials: `SPPCodeSigning-Password` (password) + `SPPCodeSigning-TotpPrivateKey` (TOTP)
+- The `-override` flag signs the JAR **in place** (no separate output file)
+- `ENVIRONMENT_NAME=PROD` is required for production signing (vs sandbox)
+- No `CREDENTIAL_ID` is needed when the eSigner account has only one certificate
+- Runs as a **post-build step** after Maven completes, not as a Maven plugin
+
+## CodeSignTool pitfalls (IMPORTANT)
+
+**Do NOT attempt to run CodeSignTool directly on the build agent.** The standalone
+CodeSignTool v1.3.2 is compiled for Java 11 and has strict JVM compatibility requirements:
+
+- **Java 8** → `UnsupportedClassVersionError` (class file version 55.0, needs Java 11+)
+- **Java 11** → Works, but requires a separate JDK install on the build agent
+- **Java 17+** → `IllegalAccessError` due to JPMS module access restrictions
+
+The **Docker image is the correct approach** — it bundles a compatible JRE inside the
+container, isolating CodeSignTool from the host Java version entirely. The build agent
+only needs Docker installed (which Azure Pipelines `ubuntu-latest` provides by default).
+
+## Maven Central publishing
+
+Publishing uses the `central-publishing-maven-plugin` v0.7.0 with `autoPublish: false`
+and `waitUntil: validated`. The plugin's `publishingServerId: central` maps to the
+`<server id="central">` entry in `settings/settings.xml`.
+
+**SNAPSHOT publishing** requires:
+- `central-publishing-maven-plugin` v0.7.0+ (earlier versions don't support SNAPSHOTs)
+- Explicit enablement per namespace at central.sonatype.com → Namespaces → dropdown →
+  "Enable SNAPSHOTs"
+- Without enablement, SNAPSHOT deploys return **403 Forbidden**
+- SNAPSHOTs are not validated, can be overwritten, and are cleaned up after ~90 days
+
+## GitHub Packages publishing
+
+Uses `mvn deploy:deploy-file` with explicit artifact coordinates. **Do NOT use
+`-DpomFile=pom.xml`** — the `deploy-file` goal reads the pom literally without resolving
+Maven properties. Since our pom has `<version>${revision}</version>`, it would see
+`${revision}` as the literal version string (invalid characters: `$`, `{`, `}`). Instead,
+specify coordinates directly: `-DgroupId=... -DartifactId=... -Dversion=... -Dpackaging=jar`.
+
+Authentication uses a `<server id="github">` entry in `settings/settings.xml` with
+`${githubusername}` and `${githubtoken}` properties, resolved via `-D` flags on the
+command line.
+
+## Azure Pipelines variable scoping (CRITICAL pitfall)
+
+Azure Pipelines has two expression syntaxes with **very different scoping rules**:
+
+- **`${{ variables.X }}`** — Compile-time expression. Can **only** see variables defined
+  in the **same template file**. Variables from other templates are invisible at compile
+  time, even if they are in the same pipeline.
+- **`$(X)`** — Runtime macro. Resolves **after** all variable scopes (pipeline + job) are
+  merged. Works across template boundaries.
+
+This means:
+- `${{ if eq(variables.isPrerelease, 'true') }}` in `job-variables.yml` **cannot** see
+  `isPrerelease` defined in `global-variables.yml` — it will always evaluate to false.
+- The fix: compute dependent values (like `versionSuffix`) in the **same template** as
+  the variables they reference, then use `$(versionSuffix)` runtime macros elsewhere.
+- Also note: `${{ true }}` as a variable value becomes the string `'True'` (capital T).
+  Use the string `'true'` (lowercase) to avoid comparison mismatches.
+
+### Example of the scoping pitfall
+
+```yaml
+# global-variables.yml — defines isPrerelease
+variables:
+  isPrerelease: 'true'
+
+# job-variables.yml — WRONG: can't see isPrerelease from global-variables.yml
+variables:
+  versionSuffix: ${{ if eq(variables.isPrerelease, 'true') }}-SNAPSHOT${{ else }}${{ endif }}
+  # ↑ Always evaluates to empty string because isPrerelease is invisible here
+
+# FIX: compute versionSuffix in global-variables.yml alongside isPrerelease,
+# then reference as $(versionSuffix) runtime macro in job-variables.yml
+```
+
+## Pipeline modification checklist
+
+When modifying the CI/CD pipeline:
+1. **Test GPG signing with `mvn deploy`**, not `mvn package` (GPG is in `verify` phase)
+2. **Never use `-DpomFile=pom.xml`** with `deploy:deploy-file` — use explicit coordinates
+3. **Keep compile-time conditionals in the same template** as the variables they reference
+4. **Use string `'true'`/`'false'`** for boolean pipeline variables, not `${{ true }}`
+5. **Verify CodeSignTool via Docker only** — never install it directly on the build agent
+6. **All credentials flow through `settings/settings.xml`** via Maven property placeholders
+   resolved by `-D` flags — Azure DevOps auto-masks vault secrets in logs
+
+## Full deploy command reference
+
+The complete `mvn deploy` invocation for a release build (for reference):
+
+```bash
+mvn deploy -P release \
+    --settings settings/settings.xml \
+    "-Drevision=$(version)" \
+    "-Dsigningkeystorepassword=$(SigningStorePassword)" \
+    "-Dgpgkeyname=$(gpgKeyName)" \
+    "-Dcentralusername=$(SonatypeUserToken)" \
+    "-Dcentralpassword=$(SonatypeRepositoryPassword)"
+```
+
+All `-D` properties map to `<server>` entries in `settings/settings.xml` via Maven
+property placeholders (e.g., `<passphrase>${signingkeystorepassword}</passphrase>`).
+Azure DevOps automatically masks vault secrets in log output.