fix(xtest): Fix EC wrapping tests and add debugging guide

[dmihalcik-virtru]

Summary

Fixes test failures related to EC wrapping and key management by ensuring proper configuration and key consistency across KAS instances. Adds comprehensive debugging documentation for AI agents and developers working with the xtest framework.

Changes

1. Fix KAS Key Management Root Key Handling (xtest/scripts/services/kas-start.sh)

Problem: Key management KAS instances (km1, km2) were generating their own root keys instead of using the platform's root key. When the platform advertises a base_key for EC wrapping, the SDK automatically uses EC wrapping, which derives keys from root_key + base_key. Different root keys resulted in "cipher: message authentication failed" errors during decrypt.

Fix: Updated kas-start.sh to:

• Use the platform's root_key from opentdf-dev.yaml for key management instances
• Fall back to generating a shared key only if platform doesn't have one
• Added explanatory comments about why this is critical for base_key functionality

Impact: Fixes 9 ABAC test failures that were failing with decrypt errors.

2. Update Manifest Schema (xtest/manifest.schema.json)

Problem: Manifest validation tests were failing because the schema only allowed ["wrapped", "remote"] as valid KAO types, but EC wrapping produces "ec-wrapped" type KAOs.

Fix: Added "ec-wrapped" to the enum of valid key access object types.

Impact: Fixes 2 manifest validity test failures.

3. Add Comprehensive Debugging Guide (AGENTS.md)

New file: Created a 400+ line debugging guide documenting:

• Test framework structure and usage
• Local environment setup with tmux
• Key concepts (EC vs RSA wrapping, base_key behavior, root key requirements)
• Common test failures with specific debugging steps
• Debugging workflow and best practices
• Quick reference commands

Purpose: Help AI agents (Haiku LLM) and developers debug test failures more efficiently by understanding the xtest framework architecture and common pitfalls.

4. Update .gitignore

Added /xtest/logs/ to prevent committing local test execution logs.

Test Results

Before fixes: 25 passed, 18 failed, 8 skipped, 4 errors
After fixes: 38 passed, 8 failed, 8 skipped, 0 errors

The remaining 8 failures are legacy tests that require specific encryption keys used when creating golden TDFs (expected failures).

Example: Running a Specific Test

# Navigate to xtest directory
cd tests/xtest

# Start local test environment (starts platform + 6 KAS instances)
./scripts/local-test.sh start

# Set required environment variables
export SCHEMA_FILE="$(pwd)/manifest.schema.json"
export OT_ROOT_KEY=$(yq e '.services.kas.root_key' ../../platform/opentdf-dev.yaml)

# Run a specific test
uv run pytest test_tdfs.py::test_tdf_roundtrip --sdks go -v

# Run all ABAC tests
uv run pytest test_abac.py --sdks go -v

# Run full test suite with Go SDK
uv run pytest --sdks go -v

# Check environment status
./scripts/local-test.sh status

Related Issues

• Fixes ABAC autoconfigure test failures
• Fixes manifest validation test failures
• Improves test debugging experience
• Documents key management and EC wrapping architecture

Checklist

• Tests pass locally with these changes
• Added documentation (AGENTS.md)
• Fixed root key consistency issue
• Updated manifest schema for ec-wrapped support

[gemini-code-assist]

Summary of Changes

Hello @dmihalcik-virtru, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the stability and debuggability of the xtest framework by resolving critical issues related to EC wrapping and key management, which were causing numerous test failures. It also introduces extensive documentation and a new set of robust shell scripts to standardize and simplify the local test environment setup and troubleshooting process. These changes collectively enhance the developer experience and ensure more reliable test outcomes.

Highlights

• KAS Key Management Root Key Handling Fix: Resolved issues where key management KAS instances were generating their own root keys instead of using the platform's root key, leading to 'cipher: message authentication failed' errors during decryption. The fix ensures consistent key derivation across KAS instances, resolving 9 ABAC test failures.
• Manifest Schema Update for EC Wrapping: Updated xtest/manifest.schema.json to include 'ec-wrapped' as a valid Key Access Object (KAO) type. Previously, the schema only allowed 'wrapped' and 'remote', causing validation failures for EC-wrapped TDFs. This change fixes 2 manifest validity test failures.
• Comprehensive Debugging Guide Added: Introduced a new file, AGENTS.md, which provides a detailed debugging guide for the xtest framework. This guide covers test structure, local environment setup, key concepts (EC vs RSA wrapping, base_key, root keys), common test failures with debugging steps, and best practices, aiming to assist AI agents and developers.
• Refactored KAS Fixture Naming: Renamed KAS-related fixtures in xtest/fixtures/attributes.py and xtest/fixtures/kas.py from generic names like value1, value2, attr, and ns to more descriptive names like alpha, beta, gamma, and delta to align with CI workflow naming conventions and improve clarity.
• New Local Test Environment Management Scripts: Added a suite of new shell scripts (cleanup.sh, local-test.sh, common.sh, tmux-helpers.sh, docker-up.sh, kas-start.sh, platform-start.sh, provision.sh, init-keys.sh, trust-cert.sh) to streamline the setup, management, and teardown of the local xtest environment, including Docker containers, platform services, and multiple KAS instances within a tmux session.
• .gitignore Update: Added /xtest/logs/ to the .gitignore file to prevent local test execution logs from being committed to the repository.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[sonarqubecloud]

Quality Gate passed

Issues
59 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[gemini-code-assist]

Code Review

This pull request significantly improves the xtest framework by addressing critical EC wrapping and key management issues, enhancing test reliability, and providing comprehensive debugging documentation. The changes ensure consistent root key handling across KAS instances, update the manifest schema for ec-wrapped KAOs, and introduce robust shell scripts for local environment management. The new AGENTS.md guide is a valuable addition for developers and AI agents, though some minor inconsistencies in tmux session and window names should be addressed for maximum clarity.

[gemini-code-assist]

The tmux session name mentioned here ('local-test') is inconsistent with the actual session name defined in xtest/scripts/lib/common.sh (xtest). Please update this to reflect the correct session name for consistency.

Suggested change

	# - platform: Main OpenTDF platform (port 8080)
	# This creates tmux session 'xtest' with windows:

[gemini-code-assist]

The window names listed here (e.g., alpha, beta) do not match the actual window names created by tmux-helpers.sh (e.g., kas-alpha, kas-beta). Please update these descriptions to accurately reflect the window names for better guidance.

Suggested change

	# - alpha: KAS instance (port 8181)
	# - beta: KAS instance (port 8282)
	# - gamma: KAS instance (port 8383)
	# - delta: KAS instance (port 8484)
	# - km1: Key management KAS (port 8585)
	# - km2: Key management KAS (port 8686)
	# - platform: Main OpenTDF platform (port 8080)
	# - kas-alpha: KAS instance (port 8181)
	# - kas-beta: KAS instance (port 8282)
	# - kas-gamma: KAS instance (port 8383)
	# - kas-delta: KAS instance (port 8484)
	# - kas-km1: Key management KAS (port 8585)
	# - kas-km2: Key management KAS (port 8686)

[gemini-code-assist]

The tmux session name local-test is inconsistent with the xtest session name defined in common.sh. Please update this command for accuracy.

Suggested change

	tmux attach -t local-test
	tmux attach -t xtest

[gemini-code-assist]

The window navigation shortcut Ctrl-B then number (0-6) is incorrect. According to tmux-helpers.sh, there are 10 windows (0-9). Please update the range to 0-9 for accuracy.

Suggested change

	# Ctrl-B d
	# Ctrl-B then number (0-9)

[gemini-code-assist]

The tmux session name local-test is inconsistent with the xtest session name defined in common.sh. Please update this command for accuracy.

Suggested change

	tmux attach -t local-test
	tmux attach -t xtest

[gemini-code-assist]

The tmux session name local-test is inconsistent with the xtest session name defined in common.sh. Please update this command for accuracy.

Suggested change

	tmux kill-session -t local-test
	tmux kill-session -t xtest

[gemini-code-assist]

The tmux session name local-test is inconsistent with the xtest session name defined in common.sh. Please update this command for accuracy.

Suggested change

	# Attach to tmux
	tmux attach -t xtest