Add ISM-X optional attestation bridge (v0.3.1) — DB & CLI integration

[Freeky7819]

Summary

This PR adds an optional attestation layer to protect database access in MCP-for-Database.
It uses Ed25519-signed “passports” and HMAC-SHA256 commitments with short-lived, single-use capability leases (replay protection). A remote /verify endpoint is preferred; a local verification fallback is provided.

What’s included

• authy_bridge/ (client helper + DB wrapper example)
• ismx/passport.py (fixed TTL verify)
• tokens.py (single-use capability leases, consume=true)
• auth0_utils.py (Auth0 RS256 verify with thread-safe JWKS cache)
• examples/mcp_integration.py (FastAPI example)
• tests/test_comprehensive.py (end-to-end tests)
• docs/ (ARCHITECTURE, SECURITY, PR_MCP, certification & quick reference)

How to use (quick)

1. pip install requests pynacl httpx fastapi "python-jose[cryptography]" pytest
2. Set env:
   • ISMX_VERIFY_URL=http://127.0.0.1:8010/verify
   • ISMX_PUBKEY_B64=<Ed25519 public key (base64)>
   • ISMX_SCOPE=db.query
   • ISMX_TAG_KEY_B64=<base64 32-byte secret>
3. Wrap queries:

from authy_bridge.example_db_bridge import run_query_with_authy
rows = run_query_with_authy("SELECT * FROM customers LIMIT 10;", passport_b64=DEMO_PASSPORT_B64)

[Freeky7819]

Hi! 👋
All lint and build issues have been resolved and the branch is now up to date.
The workflows are awaiting maintainer approval — once approved, CI should complete cleanly.
This PR is ready for review and merge. ✅

[Limeload]

@Freeky7819

First off, thank you for putting in the time and effort to build this attestation and capability-lease layer — it’s clear there’s been a lot of thought put into the security design and documentation.

That said, this PR introduces significant architectural changes that go beyond the current project scope. It modifies core access flows and dependencies (e.g., introducing new verification endpoints, passport signing, and external key management), which could affect maintainability and existing integrations.

Before merging something of this magnitude, I’d like to:

• Understand the motivation and intended use cases — is this aimed at production-grade attestation or research/demo purposes?
• Discuss whether these security layers could be modularized or made optional so that the base MCP-for-Database logic remains lightweight.
• Review potential breaking changes and confirm backwards compatibility.

Could you please open a short design discussion or ADR (Architecture Decision Record) summarizing:

• Problem statement / threat model
• Proposed solution (in brief)
• Impact on existing code and configuration
• Rollout or feature-flag strategy

Once that’s available, we can review as a team and decide whether to merge, refactor into an experimental branch, or stage the changes incrementally.

Thanks again for contributing — this is a valuable direction to explore, but I want to make sure it aligns with the project roadmap.

[Freeky7819]

Thanks for the thoughtful review — agreed on scope and maintainability.
I’ve converted this PR to Draft and will split the changes behind opt-in feature flags with no-op adapters so the default remains lightweight and fully backward-compatible.
I’ll also open a short ADR covering threat model, design, impact, and a staged rollout plan.

Proposed plan:

1. Move attestation/lease logic into authy/ and caplease/ modules.
2. Add MCPX_ATTESTATION / MCPX_CAPLEASE flags (default OFF).
3. Provide docs/adr/000x-attestation-caplease.md, config examples, and a test matrix.

If that direction sounds good, I’ll push the refactor and ADR shortly.

[Limeload]

Thanks for the thoughtful review — agreed on scope and maintainability. I’ve converted this PR to Draft and will split the changes behind opt-in feature flags with no-op adapters so the default remains lightweight and fully backward-compatible. I’ll also open a short ADR covering threat model, design, impact, and a staged rollout plan.

Proposed plan:

1. Move attestation/lease logic into authy/ and caplease/ modules.
2. Add MCPX_ATTESTATION / MCPX_CAPLEASE flags (default OFF).
3. Provide docs/adr/000x-attestation-caplease.md, config examples, and a test matrix.

If that direction sounds good, I’ll push the refactor and ADR shortly.

Thanks @Freeky7819 — that sounds like a solid plan. 👍
I really appreciate you making it opt-in with feature flags and adding an ADR for clarity.

Once the refactor and ADR are up, I’ll take a look and we can review it as a self-contained feature branch — no rush on merging, just want to make sure everything stays stable and consistent with the current goals.

Thanks again for being proactive and flexible.