A Python implementation of the SchemaPin protocol for cryptographic schema integrity verification of AI tools.

SchemaPin provides cryptographic verification of AI tool schemas using ECDSA P-256 signatures and Trust-On-First-Use (TOFU) key pinning. This Python implementation serves as the reference implementation for the protocol.

This release adds two additive, optional trust signals. v1.3 verifiers ignore both fields and continue to work unchanged.

• Signature expiration (expires_at) — SkillSigner.sign_with_options(...) with a SignOptions(expires_in=timedelta(...)) writes an expires_at timestamp into .schemapin.sig (and bumps schemapin_version to "1.4"). Verifiers past the expiration emit a signature_expired warning but stay valid=True (degraded, not failed). The VerificationResult gains expired: bool and expires_at: Optional[str] fields. See the Signature Expiration guide.
• DNS TXT cross-verification — _schemapin.{domain} TXT records of the form v=schemapin1; kid=...; fp=sha256:<hex> are cross-checked against the discovery key. New module schemapin.dns exposes DnsTxtRecord, parse_txt_record, verify_dns_match, txt_record_name, and fetch_dns_txt. The high-level entry point is SkillSigner.verify_skill_offline_with_dns(..., dns_txt=...). A fingerprint mismatch fails with ErrorCode.DOMAIN_MISMATCH; an absent record is a no-op. See the DNS TXT guide.

DNS lookups depend on dnspython, which is optional — install with pip install schemapin[dns] (or pip install dnspython). The parsing and match helpers themselves have no extra dependencies.

• ECDSA P-256 Cryptography: Industry-standard elliptic curve signatures
• Schema Canonicalization: Deterministic JSON serialization for consistent hashing
• Public Key Discovery: Automatic retrieval from .well-known/schemapin.json endpoints
• Key Pinning: Trust-On-First-Use security model with SQLite storage
• High-Level Workflows: Simple APIs for both developers and clients
• Comprehensive Testing: Full test suite with security validation

# Install latest stable version
pip install schemapin

# Install with development dependencies
pip install schemapin[dev]

# Install with testing dependencies only
pip install schemapin[test]

# Clone repository and install in development mode
git clone https://github.com/thirdkey/schemapin.git
cd schemapin/python
pip install -e .[dev]

After installation, the following CLI tools will be available:

• schemapin-keygen - Generate cryptographic key pairs
• schemapin-sign - Sign JSON schemas
• schemapin-verify - Verify signed schemas

SchemaPin provides three command-line tools for common operations:

Generate ECDSA or RSA key pairs with optional .well-known template:

# Generate ECDSA key pair with .well-known template
schemapin-keygen --type ecdsa --developer "Your Company" --well-known

# Generate RSA 4096-bit key pair
schemapin-keygen --type rsa --key-size 4096 --output-dir ./keys

# Generate keys in DER format
schemapin-keygen --type ecdsa --format der --prefix mykeys

Sign JSON schema files with private keys:

# Sign a single schema
schemapin-sign --key private.pem --schema schema.json --output signed.json

# Sign with metadata
schemapin-sign --key private.pem --schema schema.json --developer "Your Company" --version "1.0"

# Batch sign multiple schemas
schemapin-sign --key private.pem --batch ./schemas/ --output-dir ./signed/

# Sign from stdin
echo '{"type": "object"}' | schemapin-sign --key private.pem --stdin

Verify signed schemas with public keys or discovery:

# Verify with public key
schemapin-verify --schema signed.json --public-key public.pem

# Verify with domain discovery and interactive pinning
schemapin-verify --schema signed.json --domain example.com --tool-id my-tool --interactive

# Batch verify with auto-pinning
schemapin-verify --batch ./signed/ --domain example.com --auto-pin

# Verify from stdin with JSON output
echo '{"schema": {...}, "signature": "..."}' | schemapin-verify --stdin --public-key public.pem --json

Run the CLI examples script to see detailed usage patterns:

cd python/examples
python cli_usage_examples.py

from schemapin.utils import SchemaSigningWorkflow, create_well_known_response
from schemapin.crypto import KeyManager

# 1. Generate key pair
private_key, public_key = KeyManager.generate_keypair()
private_key_pem = KeyManager.export_private_key_pem(private_key)
public_key_pem = KeyManager.export_public_key_pem(public_key)

# 2. Sign your tool schema
schema = {
    "name": "calculate_sum",
    "description": "Calculates the sum of two numbers",
    "parameters": {
        "type": "object",
        "properties": {
            "a": {"type": "number", "description": "First number"},
            "b": {"type": "number", "description": "Second number"}
        },
        "required": ["a", "b"]
    }
}

signing_workflow = SchemaSigningWorkflow(private_key_pem)
signature = signing_workflow.sign_schema(schema)

# 3. Create .well-known response
well_known_response = create_well_known_response(
    public_key_pem,
    "Your Organization",
    "contact@yourorg.com"
)

# Host well_known_response at https://yourdomain.com/.well-known/schemapin.json

from schemapin.utils import SchemaVerificationWorkflow

verification_workflow = SchemaVerificationWorkflow()

# Verify schema with automatic key pinning
result = verification_workflow.verify_schema(
    schema,
    signature,
    "yourdomain.com/calculate_sum",
    "yourdomain.com",
    auto_pin=True
)

if result['valid']:
    print("✅ Schema signature is valid")
    if result['first_use']:
        print("🔑 Key pinned for future use")
else:
    print("❌ Schema signature is invalid")
    print("Error:", result['error'])

• canonicalize_schema(schema) - Convert schema to canonical string format
• hash_canonical(canonical) - SHA-256 hash of canonical string
• canonicalize_and_hash(schema) - Combined canonicalization and hashing

• generate_keypair() - Generate new ECDSA P-256 key pair
• export_private_key_pem(private_key) - Export private key to PEM format
• export_public_key_pem(public_key) - Export public key to PEM format
• load_private_key_pem(pem_data) - Load private key from PEM
• load_public_key_pem(pem_data) - Load public key from PEM

• sign_hash(hash_bytes, private_key) - Sign hash with private key
• verify_signature(hash_bytes, signature, public_key) - Verify signature
• sign_schema_hash(schema_hash, private_key) - Sign schema hash
• verify_schema_signature(schema_hash, signature, public_key) - Verify schema signature

• fetch_well_known(domain) - Fetch .well-known/schemapin.json
• get_public_key_pem(domain) - Get public key from domain
• get_developer_info(domain) - Get developer information

• pin_key(tool_id, public_key_pem, domain, developer_name) - Pin public key
• get_pinned_key(tool_id) - Get pinned key for tool
• is_key_pinned(tool_id) - Check if key is pinned
• list_pinned_keys() - List all pinned keys
• remove_pinned_key(tool_id) - Remove pinned key

workflow = SchemaSigningWorkflow(private_key_pem)
signature = workflow.sign_schema(schema)

workflow = SchemaVerificationWorkflow()
result = workflow.verify_schema(schema, signature, tool_id, domain, auto_pin)

Run the included examples:

# Tool developer workflow
cd python/examples
python tool_developer.py

# Client verification workflow  
python client_verification.py

cd python
python -m pytest tests/ -v

# Run code quality checks
ruff check .
bandit -r . --exclude tests/

• Python 3.8 or higher
• cryptography library for ECDSA operations
• requests library for HTTP operations
• sqlite3 (built-in) for key storage

• Private Key Security: Store private keys securely and never expose them
• HTTPS Required: Always use HTTPS for .well-known endpoint discovery
• Key Pinning: Review pinned keys periodically and verify authenticity
• Signature Verification: Always verify signatures before using tool schemas

This Python implementation is designed to be fully compatible with the JavaScript implementation:

• Identical schema canonicalization results
• Compatible ECDSA P-256 signatures
• Same .well-known endpoint format
• Interoperable key formats (PEM)

MIT License - see LICENSE file for details.

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

For issues and questions:

• GitHub Issues: SchemaPin Repository
• Documentation: See TECHNICAL_SPECIFICATION.md
• Examples: Check the examples/ directory