chore(xtest): Add audit & log assertions

.github/workflows/check.yml

@@ -24,6 +24,8 @@ jobs:
           python-version: '3.14'
       - name: Install uv
         uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          enable-cache: false
       - name: Install dependencies
         run: uv sync --extra dev
         working-directory: xtest

.github/workflows/xtest.yml

@@ -245,6 +245,7 @@ jobs:
           platform-ref: ${{ fromJSON(needs.resolve-versions.outputs.platform-tag-to-sha)[matrix.platform-tag] }}
           ec-tdf-enabled: true
           extra-keys: ${{ steps.load-extra-keys.outputs.EXTRA_KEYS }}
+          log-type: json
 
       - name: Set up Python 3.14
         uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
@@ -444,15 +445,15 @@ jobs:
       - name: Validate xtest helper library (tests of the test harness and its utilities)
         if: ${{ !inputs }}
         run: |-
-          uv run pytest --html=test-results/helper-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" test_self.py
+          uv run pytest --html=test-results/helper-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" test_self.py test_audit_logs.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_TAG: ${{ matrix.platform-tag }}
 
       ######## RUN THE TESTS #############
       - name: Run legacy decryption tests
         run: |-
-          uv run pytest -n auto --dist loadscope --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v --focus "$FOCUS_SDK" test_legacy.py
+          uv run pytest -n auto --dist worksteal --html=test-results/sdk-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v --focus "$FOCUS_SDK" test_legacy.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_DIR: "../../${{ steps.run-platform.outputs.platform-working-dir }}"
@@ -504,6 +505,7 @@ jobs:
           ec-tdf-enabled: true
           kas-name: alpha
           kas-port: 8181
+          log-type: json
           root-key: ${{ steps.km-check.outputs.root_key }}
 
       - name: Start additional kas
@@ -514,6 +516,7 @@ jobs:
           ec-tdf-enabled: true
           kas-name: beta
           kas-port: 8282
+          log-type: json
           root-key: ${{ steps.km-check.outputs.root_key }}
 
       - name: Start additional kas
@@ -524,6 +527,7 @@ jobs:
           ec-tdf-enabled: true
           kas-name: gamma
           kas-port: 8383
+          log-type: json
           root-key: ${{ steps.km-check.outputs.root_key }}
 
       - name: Start additional kas
@@ -534,6 +538,7 @@ jobs:
           ec-tdf-enabled: true
           kas-port: 8484
           kas-name: delta
+          log-type: json
           root-key: ${{ steps.km-check.outputs.root_key }}
 
       - name: Start additional KM kas (km1)
@@ -545,6 +550,7 @@ jobs:
           key-management: ${{ steps.km-check.outputs.supported }}
           kas-name: km1
           kas-port: 8585
+          log-type: json
           root-key: ${{ steps.km-check.outputs.root_key }}
 
       - name: Start additional KM kas (km2)
@@ -556,16 +562,34 @@ jobs:
           kas-name: km2
           key-management: ${{ steps.km-check.outputs.supported }}
           kas-port: 8686
+          log-type: json
           root-key: ${{ steps.km-check.outputs.root_key }}
 
       - name: Run attribute based configuration tests
         if: ${{ steps.multikas.outputs.supported == 'true' }}
-        run: |-
-          uv run pytest -n auto --dist loadscope --html=test-results/attributes-${FOCUS_SDK}-${PLATFORM_TAG}.html --self-contained-html --sdks-encrypt "${ENCRYPT_SDK}" -ra -v --focus "$FOCUS_SDK" test_abac.py
+        run: >-
+          uv run pytest
+          -ra
+          -v
+          --numprocesses auto
+          --dist loadscope
+          --html test-results/attributes-${FOCUS_SDK}-${PLATFORM_TAG}.html
+          --self-contained-html
+          --audit-log-dir test-results/audit-logs
+          --sdks-encrypt "${ENCRYPT_SDK}"
+          --focus "$FOCUS_SDK"
+          test_abac.py
         working-directory: otdftests/xtest
         env:
           PLATFORM_DIR: "../../${{ steps.run-platform.outputs.platform-working-dir }}"
           PLATFORM_TAG: ${{ matrix.platform-tag }}
+          PLATFORM_LOG_FILE: "../../${{ steps.run-platform.outputs.platform-log-file }}"
+          KAS_ALPHA_LOG_FILE: "../../${{ steps.kas-alpha.outputs.log-file }}"
+          KAS_BETA_LOG_FILE: "../../${{ steps.kas-beta.outputs.log-file }}"
+          KAS_GAMMA_LOG_FILE: "../../${{ steps.kas-gamma.outputs.log-file }}"
+          KAS_DELTA_LOG_FILE: "../../${{ steps.kas-delta.outputs.log-file }}"
+          KAS_KM1_LOG_FILE: "../../${{ steps.kas-km1.outputs.log-file }}"
+          KAS_KM2_LOG_FILE: "../../${{ steps.kas-km2.outputs.log-file }}"
 
       - name: Upload artifact
         uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
@@ -575,6 +599,14 @@ jobs:
           name: ${{ job.status == 'success' && '✅' || job.status == 'failure' && '❌' }} ${{ matrix.sdk }}-${{matrix.platform-tag}}
           path: otdftests/xtest/test-results/*.html
 
+      - name: Upload audit logs on failure
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        if: failure()
+        with:
+          name: audit-logs-${{ matrix.sdk }}-${{ matrix.platform-tag }}
+          path: otdftests/xtest/test-results/audit-logs/*.log
+          if-no-files-found: ignore
+
   publish-results:
     runs-on: ubuntu-latest
     needs: xct
@@ -636,4 +668,4 @@ jobs:
       - name: Success summary
         if: ${{ needs.xct.result == 'success' }}
         run: |-
-          echo "All xtest jobs succeeded." >> "$GITHUB_STEP_SUMMARY"
+           echo "All xtest jobs succeeded." >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -29,3 +29,4 @@ xtest/sdk/java/cmdline.jar
 /xtest/java-sdk/
 /xtest/sdk/go/otdfctl
 /xtest/otdfctl/
+/tmp

AGENTS.md

@@ -31,7 +31,52 @@
 - Tests assume a platform backend is reachable (Docker + Keycloak). Use `xtest/test.env` as a template:
   - `cd xtest && set -a && source test.env && set +a`
 
-## Commit & Pull Request Guidelines
+### Custom pytest Options
+- `--sdks`: Specify which SDKs to test (go, java, js)
+- `--containers`: Specify TDF container types (ztdf, ztdf-ecwrap)
+- `--no-audit-logs`: Disable audit log assertions globally
+- Environment variables:
+  - `PLATFORMURL`: Platform endpoint (default: http://localhost:8080)
+  - `OT_ROOT_KEY`: Root key for key management tests
+  - `SCHEMA_FILE`: Path to manifest schema file
+  - `DISABLE_AUDIT_ASSERTIONS`: Set to `1`, `true`, or `yes` to disable audit log assertions
+
+### Audit Log Assertions
+
+**IMPORTANT**: Audit log assertions are **REQUIRED by default**. Tests will fail during setup if KAS log files are not available.
+
+**Why Required by Default:**
+- Ensures comprehensive test coverage of audit logging functionality
+- Catches regressions in audit event generation
+- Validates clock skew handling between test machine and services
+
+**Disabling Audit Assertions:**
+
+Only disable when:
+- Running tests without services (unit tests only)
+- Debugging non-audit-related issues
+- CI environments where audit logs aren't available
+
+To disable, use either:
+```bash
+# Environment variable (preferred for CI)
+DISABLE_AUDIT_ASSERTIONS=1 uv run pytest --sdks go -v
+
+# CLI flag (preferred for local dev)
+uv run pytest --sdks go --no-audit-logs -v
+```
+
+**Setting Up Log Files:**
+
+Audit log collection requires KAS log files. Set paths via environment variables:
+```bash
+export PLATFORM_LOG_FILE=/path/to/platform.log
+export KAS_ALPHA_LOG_FILE=/path/to/kas-alpha.log
+export KAS_BETA_LOG_FILE=/path/to/kas-beta.log
+# ... etc for kas-gamma, kas-delta, kas-km1, kas-km2
+```
+
+Or ensure services are running with logs in `../../platform/logs/` (auto-discovered).
 
 - Use semantic commit/PR titles (enforced by CI): `feat(xtest): ...`, `fix(vulnerability): ...`, `docs: ...` (types: `fix|feat|chore|docs`; scopes include `xtest`, `vulnerability`, `go`, `java`, `web`, `ci`).
 - DCO sign-off is required: `git commit -s -m "feat(xtest): ..."` (see `CONTRIBUTING.md`).